upstream-hocuspocus/packages/provider-react/README.md

@hocuspocus/provider-react

React bindings for the Hocuspocus provider. Wraps the provider in components and hooks so React handles the lifecycle — including StrictMode double-mounts. Built on useSyncExternalStore.

Installation

npm install @hocuspocus/provider @hocuspocus/provider-react yjs

Requires React 18 or 19.

Usage

Wrap your collaborative subtree with HocuspocusProviderWebsocketComponent (shared WebSocket) and one or more HocuspocusRooms (one per document). Inside the room, hooks give you the provider and its state:

import {
  HocuspocusProviderWebsocketComponent,
  HocuspocusRoom,
  useHocuspocusProvider,
  useHocuspocusConnectionStatus,
} from "@hocuspocus/provider-react"

function Editor() {
  const provider = useHocuspocusProvider()
  const status = useHocuspocusConnectionStatus()
  // wire provider.document / provider.awareness into your editor
  return <div>{status}</div>
}

export function App() {
  return (
    <HocuspocusProviderWebsocketComponent url="ws://127.0.0.1:1234">
      <HocuspocusRoom name="example-document" token="super-secret-token">
        <Editor />
      </HocuspocusRoom>
    </HocuspocusProviderWebsocketComponent>
  )
}

To use with Tiptap, pass provider.document into the Collaboration extension and provider into CollaborationCaret — see the collaborative editing guide for a full example.

Exports

Components

• HocuspocusProviderWebsocketComponent — manages the shared WebSocket
• HocuspocusRoom — creates a per-document provider on the shared socket; StrictMode-safe

Hooks (must be used inside a HocuspocusRoom)

• useHocuspocusProvider() — the HocuspocusProvider instance
• useHocuspocusConnectionStatus() — 'connecting' | 'connected' | 'disconnected'
• useHocuspocusSyncStatus() — 'synced' | 'syncing'
• useHocuspocusAwareness() — array of connected users' awareness state
• useHocuspocusEvent(name, handler) — subscribe to any provider event

Documentation

Full components, hooks, and patterns reference: tiptap.dev/docs/hocuspocus/provider/react.

License

MIT — see LICENSE.md.