Cord LogoDocs
Sign inStart now

Presence Observer

Components /
Ask the Community

Enable presence on specific areas

When to use #

The PresenceObserver component observes user interaction on its DOM subtree, and marks the current user as present in the location when interaction is detected. The observer has no visual effect on the page.

The observer always registers the user as absent if the document is not currently visible per the Document.visibilityState API.

This component pairs well with:

How to use #

By itself this component does not show who is present. To display this, use <PresenceObserver /> together with the <PresenceFacepile /> component.

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

export const Example = () => (
  <>
    // 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">
      <div id="content">
        <p>lorem ipsum</p>
      </div>
    </PresenceObserver>

    // The PresenceFacepile displays who is present at the location
    <PresenceFacepile
      location={{ "page": "index", "section": "content" }}
      excludeViewer={false}
      maxUsers={7}
    />
  </>
);
Vanilla JavaScript:
<!-- 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">
  <div id="content">
    <p>lorem ipsum</p>
  </div>
</cord-presence-observer>

<!-- 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>
import { PresenceObserver } from "@cord-sdk/react";

export const Example = () => (
  <>
    // 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">
      <div id="content">
        <p>lorem ipsum</p>
      </div>
    </PresenceObserver>

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

Properties #

groupId #

required
string
The group which should be able to see the user's presence.

location #

optional
string
When the user interacts with the DOM elements within the <PresenceObserver>, they will be marked as present at this location in Cord's backend. This value defaults to the current URL.

durable #

optional
boolean
When set to true, every user will be able to see the presence indicator for any user (within the same group) who has ever been at this location at any point in the past.
When set to false, Cord will only show the users who are present at the same location at the same time.
The default is set to false.

presentEvents #

optional
object
An array of event types that Cord should listen for to determine if the user is present at the location.
Cord marks presence and absence based on JavaScript events like mouseenter. To do this, Cord uses a set of default event listeners that cover the majority of cases. You may find that you need to set additional event listeners to correctly capture a user's presence within your app.
For each event type you list, Cord will automatically create an event listener (by calling addEventListener(<event type>, () => { ... })). When these events fire, Cord will pick up the event and mark the user as present in the current location.
Example: ['scroll', 'mousemove'].
The default is set to ['mouseenter', 'focusin'].

absentEvents #

optional
object
As with presentEvents, this value is an array of event types that Cord should listen for to determine if the user has left the location.
For each event type you list, Cord will automatically create an event listener (by calling addEventListener(<event type>, () => { ... })). When these events fire, Cord will pick up the event and mark the user as absent in the current location.
Example: ['blur'].
The default is set to ['mouseleave', 'focusout'].

initialState #

optional
boolean
A true or false value to tell Cord whether or not the viewing user is present in the location.
This is necessary if the user is present at page load but may not yet have triggered any of the "present" DOM events that would cause them to be marked as present. For example, if the user loads a page, but doesn't move their mouse or use their keyboard, Cord will not automatically know that they're present on the page.
This value is useful in situations where you have many <PresenceObserver> elements in the page and you want to surface that the user is present in a particular one at page load.

observeDocument #

optional
boolean
When true, presence will be determined by whether or not the current document is visible, rather than based on the "present" and "absent" DOM events. Setting this to true means that presentEvents, absentEvents, and initialState value will be ignored.
The main situation in which you'd want to use this property is when other events (like cursor and keyboard events) are not capturing user presence accurately. A common case here is on very short pages where the majority of the visible screen is an empty window. In these situations, you may find that the user doesn't generate any mouse events since their cursor isn't within the element.
In the majority of such cases, you should consider using the <PagePresence> component instead, because it provides both a <PresenceObserver> and a <PresenceFacepile> in a single component.
You may still want a <PresenceObserver> with observeDocument set to true if you want to record presence on a page but not surface it. That is to say – you want to observe presence, but you don't want to show a facepile. This is sometimes the case when you want to record presence in one place but surface it in another place.
The default is set to false.

onChange #

optional
function
Callback invoked when presence state changes. This callback will receive a true or false value as an argument indicating whether or not the user is present at the location.

Not finding the answer you need? Ask our Developer Community

Ask Cordy