Collaborative editing hooks

Collaborative editing hooks · Strata Sync


import { createSyncClient } from "@stratasync/client";

const client = createSyncClient({
  // ... storage, transport, reactivity
  yjsTransport: createYjsTransport({
    wsEndpoint: "wss://api.example.com/yjs",
  }),
});


import { useYjsDocument } from "@stratasync/react";

function DescriptionEditor({ taskId }: { taskId: string }) {
  const {
    doc,
    isConnected,
    isSessionActive,
    participants,
    content,
    connect,
    disconnect,
    focus,
    blur,
    connectionState,
    error,
  } = useYjsDocument(
    { entityType: "Task", entityId: taskId, fieldName: "description" },
    { autoConnect: true }
  );

  if (!doc) {
    return <div>Loading editor...</div>;
  }

  return (
    <div>
      {isSessionActive && (
        <div>
          Collaborating with: {participants.map((p) => p.userId).join(", ")}
        </div>
      )}
      <RichTextEditor doc={doc} onFocus={focus} onBlur={blur} />
      {error && <div>{error.message}</div>}
    </div>
  );
}

Option	Type	Default	Description
`initialContent`	`string`	-	Initial content if the document is empty.
`autoConnect`	`boolean`	`false`	Automatically connect when the component mounts.
`editing`	`boolean`	-	Start in editing mode (signals presence).
`skip`	`boolean`	`false`	Skip connecting entirely.

Field	Type	Description
`doc`	`YDoc \| null`	The Yjs document instance. `null` before connection.
`connectionState`	`YjsConnectionState`	`"disconnected"`, `"connecting"`, `"syncing"`, or `"connected"`.
`isConnected`	`boolean`	`true` when `connectionState === "connected"`.
`isSessionActive`	`boolean`	`true` when other participants are present.
`participants`	`SessionParticipant[]`	List of current session participants.
`content`	`string`	Current text content of the document.
`connect`	`() => void`	Connect to the document.
`disconnect`	`() => void`	Disconnect from the document.
`focus`	`() => void`	Signal that you started editing.
`blur`	`() => void`	Signal that you stopped editing.
`error`	`Error \| null`	Any error that occurred.


import { useYjsPresence } from "@stratasync/react";

function TaskEditor({ taskId }: { taskId: string }) {
  const { getRef, isViewing, isEditing, focus, blur } = useYjsPresence(
    { entityType: "Task", entityId: taskId, fieldName: "description" },
    { trackFocus: true, trackVisibility: true }
  );

  return (
    <div ref={getRef()}>
      <p>Viewing: {isViewing ? "Yes" : "No"}</p>
      <p>Editing: {isEditing ? "Yes" : "No"}</p>
      <textarea onFocus={focus} onBlur={blur} />
    </div>
  );
}

Option	Type	Default	Description
`trackFocus`	`boolean`	`false`	Track focus via `focusin`/`focusout` on the ref element.
`trackVisibility`	`boolean`	`false`	Track visibility via `IntersectionObserver`.
`skip`	`boolean`	`false`	Skip presence tracking.

Field	Type	Description
`startViewing`	`() => void`	Start viewing the document.
`stopViewing`	`() => void`	Stop viewing the document.
`focus`	`() => void`	Signal editing focus.
`blur`	`() => void`	Signal editing blur.
`isViewing`	`boolean`	Whether you're viewing the document.
`isEditing`	`boolean`	Whether you're editing the document.
`getRef`	`<T extends HTMLElement>() => (element: T \| null) => void`	Ref callback for auto-tracking.


function AutoTrackedEditor({ taskId }: { taskId: string }) {
  const { getRef } = useYjsPresence(
    { entityType: "Task", entityId: taskId, fieldName: "description" },
    { trackFocus: true, trackVisibility: true }
  );

  return (
    <div ref={getRef()}>
      <textarea />
    </div>
  );
}

Collaborative editing hooks

Prerequisites

useYjsDocument

DocumentKey

UseYjsDocumentOptions

UseYjsDocumentResult

SessionParticipant

YjsConnectionState

useYjsPresence

UseYjsPresenceOptions

UseYjsPresenceResult

Auto-tracking with getRef