e0c588ca1c
Some checks failed
build / lint (22) (push) Failing after 17s
build / test (22) (push) Failing after 8s
build / lint (23) (push) Failing after 2s
build / build (22) (push) Has been skipped
build / build (23) (push) Has been skipped
build / test (23) (push) Failing after 4s
docsearch / docsearch (push) Failing after 1s
71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# @hocuspocus/provider-react
|
|
[](https://www.npmjs.com/package/@hocuspocus/provider-react)
|
|
[](https://npmcharts.com/compare/tiptap?minimal=true)
|
|
[](https://www.npmjs.com/package/@hocuspocus/provider-react)
|
|
[](https://github.com/sponsors/ueberdosis)
|
|
|
|
React bindings for the [Hocuspocus provider](../provider). Wraps the provider in components and hooks so React handles the lifecycle — including StrictMode double-mounts. Built on `useSyncExternalStore`.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
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 `HocuspocusRoom`s (one per document). Inside the room, hooks give you the provider and its state:
|
|
|
|
```tsx
|
|
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](https://tiptap.dev/docs/hocuspocus/guides/collaborative-editing) 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](https://tiptap.dev/docs/hocuspocus/provider/react).
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE.md](https://github.com/ueberdosis/hocuspocus/blob/main/LICENSE.md).
|