Skip to content
Edytor
Esc
↑↓navigate↵open⌘Jpreview
On this page

Presence

Show who is editing, with names, colors, remote carets and selections, through the document's awareness.

Presence is the short-lived state peers share while connected: who they are, and where their caret or selection is. Edytor keeps it in the document’s awareness instance, publishes each view’s selection there, and draws remote carets in every view. Presence is never stored in the document.

Name and color

The simplest way is the document’s actor: its name and color are published as the presence user field, which remote carets read.

<Edytor {server} {room} actor={{ id: 'user-42', name: 'Ada', color: '#dc2626' }} />

A shared document takes it at creation instead: createDocument({ actor: { … } }).

To set or change it later, write the user field yourself. edytor.awareness (on a view) and document.awareness are the same instance:

edytor.awareness.setLocalStateField('user', { name: 'Ada', color: '#dc2626' });
Field Type Description
name string The label drawn above the caret. No label when absent.
color string A hex color, #rgb to #rrggbbaa. Anything else falls back to #2563eb.

actor.id is published too, as the actor field, and is the id stored in attribution. user is display-only: changing the name never rewrites authorship. The shipped room relays actor.id as the socket’s verified user, whatever the client sent, so use the user id your server’s authorize returns as actor.id (attribution trust).

Remote carets and selections

Every mounted <Edytor> view draws the other clients’ selections, with no setup:

  • one caret per client, with its name label, in the client’s color;
  • a translucent highlight over the text a client has selected;
  • nothing for the local client.

Carets are bound to positions in the CRDT, not to pixel offsets, so they follow the text as anyone edits it. A caret whose anchor cannot be resolved (its text was deleted, for example) is not drawn.

A client that shares blocks (a block selection, or a view with presence={{ share: 'block' }}, below) is drawn as a bar in its color beside the blocks’ own rows, with its name label, instead of a caret. A selected inline block is published but not drawn. When one client has several views of the document open, peers see the view whose selection changed last.

The carets live in the editor’s overlay layer, next to the editable host, so they never enter the document or the editable DOM:

<div data-edytor-remote-presence>
  <span data-edytor-remote-selection data-client-id="1234"></span>
  <span data-edytor-remote-cursor data-client-id="1234">
    <span data-edytor-remote-cursor-label>Ada</span>
  </span>
  <!-- a client sharing blocks: the bar beside them -->
  <span data-edytor-remote-cursor data-edytor-remote-block data-client-id="5678">
    <span data-edytor-remote-cursor-label>Linus</span>
  </span>
</div>

The editor sets their positions inline, and each client’s color as the variable --edytor-remote-color on its caret and ranges (its label inherits it). The Notion theme paints them with it: a 2px caret, a pill with the name, a translucent range. Without the theme they are placed and unpainted: target these attributes from your stylesheet and read the variable (Without the theme).

Sharing less at scale

Every caret move is a presence write, and the room relays each one to every peer: with many people in one document, that traffic grows with the square of the crowd. A view writes its presence at most once every 50 ms by default (DEFAULT_PRESENCE_THROTTLE), so an arrow key held down or a drag costs about 20 writes a second instead of one per selection change, and the room, a single Durable Object per document, relays about 20 × (people − 1) writes a second for each person moving. Past a budget of frames (2,000 a second over all its sockets, EDYTOR_MAX_PRESENCE_FANOUT), the shipped room sends each peer the writes that waited together, the newest of each person, so a crowded room slows the remote carets down rather than its acknowledgements (the room’s presence). The presence prop trims it further per view:

<Edytor {room} {server} presence={{ share: 'block', throttle: 250 }} />
Option Values Default Effect
share 'caret', 'block', 'none' 'caret' 'caret' publishes the selection. 'block' publishes only the block holding the selection’s focus ({ blocks: [id] }; a block selection publishes its blocks): moving or typing inside a block publishes nothing, and peers see a bar beside the block instead of a caret. 'none' publishes nothing and removes the view’s entry.
throttle milliseconds 50 The least time between two presence writes of this view. The first write goes at once; later ones within the window collapse into one write of the newest selection at its end, so peers always end on where the user is. 0 writes every change at once.

The prop follows changes, so an app can narrow presence as a room fills up. Outside the component, set edytor.presence.share and edytor.presence.throttle, or pass presence to new Edytor({ presence }). Destroying the view drops a write still waiting and removes its entry. The user and actor fields are not affected: who is online stays visible with 'none'.

Who is online

edytor.presence.peers is the list of the other people in the document: every client but this one, ordered by client id, each { clientId, name?, color?, …} with the fields of its user state (the document’s actor name and color when it set no user). It is reactive: read it in markup and the list follows joins, leaves and name changes. The view listens to the awareness only while something reads the list.

<script lang="ts">
  import type { EdytorInstance } from 'edytor';

  let { edytor }: { edytor: EdytorInstance } = $props();
</script>

{#each edytor.presence.peers as person (person.clientId)}
  <span style:background={person.color}>{person.name ?? 'Anonymous'}</span>
{/each}

The instance from <Edytor bind:edytor> or useEdytor() is the same view, so peers reads the same there. Your own name is the user you set above.

What the presence wire carries

Each client publishes one JSON state:

import type { DocAnchor } from 'edytor/crdt/edytor';

type PresenceState = {
  actor?: { id: string; name?: string; color?: string };
  user?: { name?: string; color?: string };
  selections?: Record<string, ViewSelection & { t: number }>; // one entry per view
};

type ViewSelection =
  | { start: DocAnchor; end: DocAnchor; collapsed: boolean; reversed: boolean } // text
  | { blocks: string[] } // a block selection
  | { atom: string; block: string }; // a selected inline block
  • Each view writes only its own key in selections, when its selection changes, and removes it when it is destroyed. t orders the entries of one client by recency.
  • A text selection is two anchors (DocAnchor, { b, a }: a block id and a CRDT relative position) in document order, plus whether it is collapsed and whether the user selected backwards. No offsets or DOM data travel.
  • You may add your own fields with setLocalStateField (an “away” status, for example). Keep them small: every change is sent to every peer.

Lifetime

  • A client re-publishes its state every 15 seconds. A peer that stays silent for 30 seconds is dropped.
  • Closing a page or destroying the document announces the client’s departure. A beforeunload announces it too, but keeps the providers running: when an unsaved-changes prompt keeps the user on the page, editing and syncing go on, and the presence returns with its next renewal (within 15 seconds). When a socket drops without a goodbye, the edytor room announces it for the client. Safari (WebKit) can drop the departure a closing page sends (it drops the frames still queued when the page tears down, and every frame sent from pagehide), so there the departure to rely on is the room’s, at the socket’s close: behind a server of your own that announces nothing when a socket closes, a closed Safari tab’s caret can stay on the others until it expires (30 seconds).
  • Presence crosses tabs of the same browser over the same BroadcastChannel as the document.
  • A lost WebSocket connection clears the remote states on that client until it reconnects. Other tabs of the same browser keep the peers they still hear, whether the tab lost its socket or was closed. On reconnect the room’s snapshot of present peers shows them at once.

Presence is relayed, not stored: the room keeps the latest entry of each connected client in memory only, and accepts entries from a socket only for that socket’s own client id. See the room.

Was this page helpful?