Presence Facepile

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.

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" }} >
      <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.

exactMatch

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

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.

orientation

optional
string
The orientation of the facepile. Can either be horizontal or vertical.
The default is set to horizontal.

onUpdate

optional
function
Callback invoked when the presence information changes.

CSS Variables

Name Default Value
--cord-facepile-background-color
var(--cord-color-base, #FFFFFF);
--cord-avatar-border-radius
var(--cord-space-3xs, 4px);
--cord-avatar-text-color
var(--cord-color-base, #FFFFFF);
--cord-avatar-background-color
var(--cord-color-brand-primary, #121314);
--cord-avatar-text-transform
none;
--cord-tooltip-background-color
var(--cord-color-brand-primary, #121314);
--cord-tooltip-content-color
var(--cord-color-base, #FFFFFF);