Presence

Presence is used for anything that is real-time and ephemeral (meaning it doesn’t stick around after you leave). For example, cursors only matter when you are actually on the page. When you leave, they are gone and there’s no record of them.

When you want things to stay after refreshing, use persistent data and use events for real-time events that don’t rely on updating data.

Element APIs use the word awareness for presence scoped to one element. myDefaultAwareness, awareness, and setMyAwareness are still ephemeral per-user state; they just belong to a specific element instead of the page-level playhtml.presence object.

The unified API

You get one view of everyone connected, with both system fields (identity, cursor) and any custom channels you add. In vanilla JS that’s the playhtml.presence object; in React it’s the usePresence hook.

Vanilla HTML

// Set (or clear) a custom channel
playhtml.presence.setMyPresence("status", { text: "focused", emoji: "🎯" });
playhtml.presence.setMyPresence("status", null);

// Read everyone (includes the local user, flagged with isMe)
const presences = playhtml.presence.getPresences();
for (const [id, p] of presences) {
  p.isMe;            // boolean
  p.playerIdentity;  // name, colors, publicKey
  p.cursor;          // { x, y, pointer } | null
  p.status;          // your custom channel (if set)
}

// Subscribe to a specific channel — fires only when that channel changes
const unsub = playhtml.presence.onPresenceChange("status", renderStatusRow);

// Your own identity
const me = playhtml.presence.getMyIdentity();

React

import { usePresence } from "@playhtml/react";

function StatusList() {
  // presences is the live map (keyed by stable id); setMyPresence writes
  // your own; myIdentity is your name/colors/publicKey.
  const { presences, setMyPresence, myIdentity } = usePresence<{ text: string }>("status");

  return (
    <>
      <button onClick={() => setMyPresence({ text: "focused" })}>focus</button>
      {[...presences.values()].map((p) => p.status?.text)}
    </>
  );
}

The hook subscribes and unsubscribes with the component lifecycle. Your channel value lives under the channel name (p.status), not flattened onto the view.

Cursor presence subscribes the same way

Cursor movements are included as a special example of this presence.

const unsub = playhtml.presence.onPresenceChange("cursor", (presences) => {
  renderCursorPositions(presences);
});

For pixel-accurate cursor rendering (including coordinate conversion across scrolled/zoomed pages), use the cursor system directly. See the Cursors page.

Custom channels

Channel names flatten into the top-level PresenceView. Pick names that don’t collide with the system fields (playerIdentity, cursor, isMe): collisions are silently dropped.

Common shapes:

• status: { text, emoji } or a tag string for “focused / typing / afk”
• focus: { elementId } to highlight which part of the page someone is looking at
• selection: { start, end } for collaborative text editing
• cursor-chat: a short message shown beside the user’s cursor

Setting vs clearing:

Vanilla HTML

// Set: replace semantics per channel
playhtml.presence.setMyPresence("status", { text: "typing" });

// Clear: null
playhtml.presence.setMyPresence("status", null);

React

const { setMyPresence } = usePresence("status");

// Set: replace semantics per channel
setMyPresence({ text: "typing" });

// Clear: null
setMyPresence(null);

There’s no partial/merge update for a channel. When you call setMyPresence, you overwrite that channel’s value for your user.

Element awareness

Use page-level presence when the signal belongs to the room: online status, cursor position, lobby readiness, or a typing indicator that several parts of the page may read. Use element awareness when the signal only matters for one playhtml element, like “who has joined this widget” or “which color is this reader contributing here”.

In vanilla can-play, element awareness appears on the element handler data:

<button can-play id="presence-count">0 readers here</button>

<script>
  const element = document.getElementById("presence-count");
  element.defaultData = {};
  element.myDefaultAwareness = { color: "#3b82f6" };
  element.updateElement = () => {};
  element.onClick = (_event, { setMyAwareness }) => {
    setMyAwareness({ color: "#f97316" });
  };
  element.updateElementAwareness = ({ element, awareness }) => {
    const label = awareness.length === 1 ? "reader" : "readers";
    element.textContent = `${awareness.length} ${label} here`;
  };
</script>

In React, the same fields are available from withSharedState and <CanPlayElement> render props:

<CanPlayElement id="presence-count" defaultData={{}} myDefaultAwareness="#3b82f6">
  {({ awareness, setMyAwareness }) => {
    const label = awareness.length === 1 ? "reader" : "readers";
    return (
      <button onClick={() => setMyAwareness("#f97316")}>
        {awareness.length} {label} here
      </button>
    );
  }}
</CanPlayElement>

Awareness has the same lifetime as presence: it clears when the user leaves, and a late visitor does not replay it.

Isolated presence rooms

The main presence layer tracks everyone in the page’s room. When you want a presence channel scoped to something other than the page (a lobby, a document, a game table that several pages share), create a separate presence room.

Vanilla HTML

const room = playhtml.createPresenceRoom("lobby-42");

room.presence.setMyPresence("status", { text: "ready" });
const unsub = room.presence.onPresenceChange("status", renderLobby);

// When you're done (e.g. the user leaves the lobby), tear it down:
room.destroy();

createPresenceRoom(name) returns a PresenceRoom ({ presence, destroy }), where presence is the same API as playhtml.presence, backed by its own connection. Always call destroy() when the room is no longer needed; it closes the connection and clears your presence for everyone else.

React

import { usePresenceRoom } from "@playhtml/react";

function Lobby() {
  const room = usePresenceRoom("lobby-42");
  if (!room) return null; // null until joined
  room.presence.setMyPresence("status", { text: "ready" });
  return <div>{room.presence.getPresences().size} in the lobby</div>;
}

usePresenceRoom(name) joins the room and tears it down for you on unmount.

Try it live

Each dot is one reader; the yellow-glowing dot is you. Pick a color and watch yours change for everyone else. Open this page in a second tab and you’ll see two dots. Close a tab and the dot disappears. This is presence: no persistence, no replay.

Looking for a “live reactions” bursting button? That’s an event, not presence. The docs for events have a live demo.

When to use data instead

Presence is for the live sense of other people on the page. If you find yourself reaching for localStorage or a refresh-survivor, you want data, not presence.

Not sure which primitive fits? The full decision table, covering element data, page data, presence, element awareness, cursors, and events, is on data essentials.