@docx-editor.dev/pro/vue/hocuspocus
@docx-editor.dev/pro/vue/hocuspocus — Vue composable that owns a Hocuspocus room.
Import this subpath only when you use Hocuspocus. @docx-editor.dev/pro/vue does not load a network provider.
Functions (1)
useHocuspocusCollaborationfunctionSource ↗
Own a Hocuspocus collaboration room for a Vue host.
The default Pro Vue entry does not import this composable. Import it from @docx-editor.dev/pro/vue/hocuspocus so a review-only bundle does not load a network provider.
declare function useHocuspocusCollaboration(options?: MaybeRefOrGetter<UseHocuspocusCollaborationOptions | null>): UseHocuspocusCollaborationReturn;Interfaces (5)
CollaborationIdentityUpdateinterfaceSource ↗
Display-identity fields a live session can update.
actorId and role are attribution and stay immutable for the session lifetime, so this type cannot name them.
interface CollaborationIdentityUpdate| Member | Type | Summary |
|---|---|---|
| color? | string | New presence color, at most 64 characters. |
| name? | string | New display name, 1 to 256 characters after trimming. |
CollaborationSessioninterfaceSource ↗
Host-facing collaboration session.
A host reads identity, status, presence, and undo. The editor attaches [EditorCollaborationSession](EditorCollaborationSession) internally and never through this type.
interface CollaborationSession| Member | Type | Summary |
|---|---|---|
| canRedo | | Whether the shared undo history holds a local step to redo. |
| canUndo | | Whether the shared undo history holds a local step to undo. |
| documentId | string | The room's document id. |
| identity | CollaborationIdentity | The validated local identity. |
| offlineEditing? | boolean | Whether edits continue while the transport is down (`disconnected`). Set by the `offlineEditing` option; absent means true. |
| participants | | Participants in presence, this replica included. Capped at 256. |
| redo | | Redo this participant's last undone step. Returns false when refused. |
| remoteSelections | | Other participants' selections, resolved into this replica's addresses. |
| sessionId | string | Unique identity for this attachment lifetime. |
| setIdentity | | Update the display name and color mid-session, when the replica supports it. |
| status | | Current lifecycle state. |
| statusSnapshot | | Cached status, current reason, and last failure. |
| subscribeParticipants | | Call `listener` when the participant list changes. Returns the unsubscribe function. |
| subscribeRemoteSelections | | Call `listener` when a remote selection changes. Returns the unsubscribe function. |
| subscribeStatus | | Call `listener` on each status or reason change. Returns the unsubscribe function. |
| undo | | Undo this participant's last step; others' edits stay. Returns false when refused. |
UseHocuspocusCollaborationConnectOptionsinterfaceSource ↗
Arguments for [UseHocuspocusCollaborationReturn.connect](UseHocuspocusCollaborationReturn.connect).
interface UseHocuspocusCollaborationConnectOptions| Member | Type | Summary |
|---|---|---|
| bootstrap | UseHocuspocusCollaborationBootstrap | Whether to seed the room, join it, or let the peers decide. |
| identity | CollaborationIdentity | The local participant. Recorded as the author of this replica's changes. |
| offlineEditing? | boolean | Admit local edits while the transport is `disconnected`. Buffered updates merge on reconnect. On by default; pass `false` to pause editing while disconnected. See [CreateDocumentCollaborationOptions.offlineEditing](CreateDocumentCollaborationOptions.offlineEditing). |
| roomId | string | Room name on the server, also the document id. Make one with `createCollaborationRoomId`. |
| syncedTimeoutMs? | number | Bound on the wait for the server's initial sync. Default 30000 ms. |
| token? | string | (() => string | Promise<string>) | Authentication token the provider sends in its auth handshake. Pass a callback and the provider re-evaluates it on every reconnect, which is how expiring JWTs renew. |
| url | string | Hocuspocus server WebSocket URL, for example `wss://collab.example.test`. |
UseHocuspocusCollaborationOptionsinterfaceSource ↗
Input for [useHocuspocusCollaboration](useHocuspocusCollaboration).
interface UseHocuspocusCollaborationOptions| Member | Type | Summary |
|---|---|---|
| modules? | readonly EditorModule[] | Host modules. The hook adds `collaborationModule` when a room is ready. A host collaboration contribution is a configuration error and throws. |
| room? | UseHocuspocusCollaborationConnectOptions | null | Connect this room when the composable starts. Omit it and call [UseHocuspocusCollaborationReturn.connect](UseHocuspocusCollaborationReturn.connect) after the user chooses a room. A different room, server, bootstrap kind, or `actorId` leaves the old room and connects the new one, and `null` leaves. A room opened with `connect` stays. |
UseHocuspocusCollaborationReturninterfaceSource ↗
Values [useHocuspocusCollaboration](useHocuspocusCollaboration) returns.
interface UseHocuspocusCollaborationReturn| Member | Type | Summary |
|---|---|---|
| connect | (options: UseHocuspocusCollaborationConnectOptions) => Promise<CollaborationFailure | null> | Connect a room. RESOLVES with the failure, or null on success — it does not reject. |
| document | Readonly<Ref<Uint8Array | null>> | The room's document as `.docx` bytes to mount. Null until the room is ready. |
| error | Readonly<Ref<CollaborationFailure | null>> | The connect failure or session failure, or null. Check it before `document`. |
| leave | (nextDocument: Uint8Array) => void | Destroy the room and carry on editing locally. |
| modules | Readonly<Ref<readonly EditorModule[]>> | Modules to pass to the editor. They include the collaboration module once ready. |
| pending | Readonly<Ref<boolean>> | True while a connect is in progress. |
| provider | Readonly<Ref<HocuspocusProvider | null>> | The owned `@hocuspocus/provider` instance. Null while no room is connected. |
| rejoin | (nextDocument: Uint8Array) => Promise<CollaborationFailure | null> | Recover a session that reached status `error`: leave with `nextDocument`, then connect again to the same room with the same identity, url, and token. |
| session | Readonly<Ref<CollaborationSession | null>> | The live session for status and presence. Null while no room is connected. |
| unsyncedChanges | Readonly<Ref<number>> | Local changes the server has not confirmed yet. More than zero while edits made offline wait for the connection, and for a moment after each edit while online. Warn before the page closes while it is above zero, or those edits are lost: |
| ydoc | Readonly<Ref<Y.Doc | null>> | The room's shared Yjs document, owned by the composable. Null while no room is connected. |
Type aliases (1)
UseHocuspocusCollaborationBootstraptypeSource ↗
Bootstrap for one Hocuspocus room.
type UseHocuspocusCollaborationBootstrap = CollaborationBootstrap;