Cord LogoDocs
Sign inStart now

Presence Facepile

Components /
Ask the Community

See user avatar icons for who has viewed a specific location, and when

Try hovering over me
And now me!
Live Demo

When to use #

The PresenceFacepile component renders a "facepile" showing the avatar icons of users who are (or have been) present in a specific location -- for example a section within a larger page.

This component pairs well with:

How to use #

By itself, this component does not track and record presence; it only displays it. You should use it together with the <PresenceObserver /> component, which tracks user interaction to record presence.

React:
import { PresenceFacepile } from "@cord-sdk/react";

export const Example = () => (
  <>
    // The PresenceFacepile displays who is present at the location
    <PresenceFacepile
      location={{ page: "index", section: "content" }}
      excludeViewer={false}
      maxUsers={7}
    />

    // The PresenceObserver tracks and marks users as present in the
    // location when user interaction is detected
    <PresenceObserver location={{ page: "index", section: "content" }} groupId="my-group" >
      <p>Try hovering over me</p>
    </PresenceObserver>
  </>
);
Vanilla JavaScript:
<!-- The cord-presence-facepile displays who is present at the location -->
<cord-presence-facepile
  location='{ "page": "index", "section": "content" }'
  exclude-viewer="false"
  max-users="7"
></cord-presence-facepile>

<!-- The cord-presence-observer tracks and marks the current user as present
in the location when user interaction is detected -->
<cord-presence-observer location='{ "page": "index", "section": "content" }' group-id="my-group">
  <p>Try hovering over me</p>
</cord-presence-observer>
import { PresenceFacepile } from "@cord-sdk/react";

export const Example = () => (
  <>
    // The PresenceFacepile displays who is present at the location
    <PresenceFacepile
      location={{ page: "index", section: "content" }}
      excludeViewer={false}
      maxUsers={7}
    />

    // The PresenceObserver tracks and marks users as present in the
    // location when user interaction is detected
    <PresenceObserver location={{ page: "index", section: "content" }} groupId="my-group" >
      <p>Try hovering over me</p>
    </PresenceObserver>
  </>
);
Copy

Properties #

location #

optional
string
The location to watch for users.
The default is set to the current URL.

partialMatch #

optional
boolean
When true, users in any partially matching location are shown. When false, only users in the component's exact location are shown in the facepile.
The default is set to true.

onlyPresentUsers #

optional
boolean
When true, only users with ephemeral presence are shown in the facepile. When false, users with ephemeral or durable presence are shown.
The default is set to false.

excludeViewer #

optional
boolean
When true, users do not see their own avatars in the facepile. When false, users see themselves in the facepile.
The default is set to false.

maxUsers #

optional
number
The maximum number of avatars to display in the facepile. If there are more than this many avatars to show, a "+N" indicator will be shown after the faces to indicate how many avatars are not being shown.
The default is set to 5.

onUpdate #

optional
function
Callback invoked when the presence information changes.

CSS customization #

If you want to customize this component, you can target the classes below in your app's CSS. These are guaranteed to be stable.

Class nameDescription
.cord-facepile
Applied to the container div. This class is always present.
.cord-other-users
Applied to the "+N" indicator, which is shown after the faces to indicate how many avatars are not being shown.

Not finding the answer you need? Ask our Developer Community

Ask Cordy