> ## Documentation Index > Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # API reference > Every hook and handle on the superdoc/ui surface. Handwritten reference for the controller surface. Mirrors the page order above. ## Provider and hooks Imported from `superdoc/ui/react`. ### `` Holds one controller per editor mount. Wrap your app once. ```tsx theme={null} {children} ``` ### `useSetSuperDoc()` Returns the setter the editor mount component calls in `onReady`. Most components don't use this directly. ```tsx theme={null} const setSuperDoc = useSetSuperDoc(); setSuperDoc(superdoc)} /> ``` ### `useSuperDocUI()` Returns the controller, or `null` until ready. ```tsx theme={null} const ui = useSuperDocUI(); ui?.commands.get('bold')?.execute(); ``` ### `useSuperDocCommand(id)` Subscribes to one command's state. See [Toolbar and commands](/editor/custom-ui/toolbar-and-commands). ```ts theme={null} const bold = useSuperDocCommand('bold'); // { active: boolean; disabled: boolean; value: unknown; source: 'built-in' | 'custom' } ``` ### `useSuperDocSelection()` Returns the live selection slice. See [Selection and viewport](/editor/custom-ui/selection-and-viewport). ```ts theme={null} const selection = useSuperDocSelection(); // { empty, target, selectionTarget, activeMarks, activeCommentIds, activeChangeIds, quotedText } ``` ### `useSuperDocComments()` Returns the comments slice. See [Comments](/editor/custom-ui/comments). ```ts theme={null} const { items, total, activeIds } = useSuperDocComments(); ``` ### `useSuperDocTrackChanges()` Returns the tracked-changes slice. See [Track changes](/editor/custom-ui/track-changes). ```ts theme={null} const { items, total, activeId } = useSuperDocTrackChanges(); ``` ### `useSuperDocDocument()` Returns the document slice. See [Document control](/editor/custom-ui/document-control). ```ts theme={null} const { ready, mode, dirty } = useSuperDocDocument(); ``` ### `useSuperDocToolbar()` Returns the full toolbar snapshot. Re-renders on any command change. Prefer `useSuperDocCommand` per button when possible. ```ts theme={null} const toolbar = useSuperDocToolbar(); // { context, commands: Record } ``` ### `useSuperDocFontOptions()` Returns font-family picker options for custom toolbar UIs. The list includes the built-in defaults plus fonts used by the active document, sorted alphabetically. ```ts theme={null} const options = useSuperDocFontOptions(); // [{ label: 'Calibri', value: 'Calibri', previewFamily: 'Carlito' }, ...] ``` Use `option.value` with `ui.toolbar.execute('font-family', option.value)`. Use `option.previewFamily` only to render the row preview. ### `useSuperDocSlice(picker, initial)` Subscribe to any slice from `ui.select(...)`. Use when the typed hooks above don't cover what you need. ```ts theme={null} const documentMode = useSuperDocSlice( (ui) => ui.select((state) => state.documentMode, Object.is), null, ); ``` ### `useSuperDocHost()` Returns the host SuperDoc instance. Reserved for operations the controller doesn't bridge yet. ```ts theme={null} const host = useSuperDocHost(); ``` ## Controller handles Imported from `superdoc/ui`. The provider handles construction; you typically reach these through `useSuperDocUI()` + the typed hooks. ### `ui.commands` Built-in dispatch and custom-command registration. ```ts theme={null} ui.commands.get('bold')?.execute(); // dynamic dispatch ui.commands.has('company.aiRewrite'); // is this id registered? ui.commands.require('company.insertClause'); // get or throw ui.commands.bold.execute(); // typed per-built-in handle ui.commands.bold.observe(({ active, disabled }) => { ... }); const reg = ui.commands.register({ // custom command id: 'company.insertClause', shortcut: 'Mod-Shift-C', // optional keyboard binding execute: ({ payload, superdoc, editor, context }) => true, getState: ({ state }) => ({ disabled: state.selection.empty }), contextMenu: { // optional right-click contribution label: 'Insert clause here', group: 'review', when: ({ entities, position, insideSelection }) => entities.length === 0 && position !== null && insideSelection !== true, }, }); reg.invalidate(); reg.unregister(); // Right-click menu items returned from getContextMenuItems carry invoke() // closures that fire execute({ context }) with the bundle bound. const items = ui.commands.getContextMenuItems( ui.viewport.contextAt({ x: event.clientX, y: event.clientY }), ); items[0]?.invoke?.(); ``` ### `ui.comments` Live snapshot, mutations, navigation. ```ts theme={null} ui.comments.getSnapshot(); // sync read ui.comments.subscribe(({ snapshot }) => {}); ui.comments.createFromSelection({ text }); ui.comments.createFromCapture(capture, { text }); ui.comments.reply(parentCommentId, { text }); ui.comments.resolve(commentId); ui.comments.reopen(commentId); ui.comments.delete(commentId); ui.comments.scrollTo(commentId); ``` ### `ui.trackChanges` Live list, accept / reject, navigation. ```ts theme={null} ui.trackChanges.getSnapshot(); ui.trackChanges.subscribe(({ snapshot }) => {}); ui.trackChanges.accept(changeId); ui.trackChanges.reject(changeId); ui.trackChanges.acceptAll(); ui.trackChanges.rejectAll(); ui.trackChanges.next(); ui.trackChanges.previous(); ui.trackChanges.scrollTo(changeId); ``` ### `ui.document` Mode, export, replace. ```ts theme={null} ui.document.getSnapshot(); // { ready, mode, dirty } ui.document.subscribe(({ snapshot }) => {}); ui.document.setMode('suggesting'); await ui.document.export({ exportType: ['docx'], commentsType: 'external', triggerDownload: true }); await ui.document.replaceFile(file); ``` ### `ui.zoom` Zoom state, viewport metrics, and the two mutations. The snapshot updates on value changes, mode-only transitions, and viewport metric updates. ```ts theme={null} ui.zoom.getSnapshot(); // { mode, value, fitZoom, min, max, metrics } ui.zoom.observe((snapshot) => {}); ui.zoom.set(125); // numeric zoom; switches the host to manual mode ui.zoom.setMode('fit-width'); // continuous fit to the available width ``` In React, `useSuperDocZoom()` returns the same snapshot plus bound `set` / `setMode` actions. The toolbar registry also exposes a `zoom-fit-width` toggle command for custom toolbars. ### `ui.selection` Live slice, capture, restore, painted geometry. ```ts theme={null} ui.selection.getSnapshot(); ui.selection.subscribe(({ snapshot }) => {}); const captured = ui.selection.capture(); // frozen, holds across focus changes const restore = ui.selection.restore(captured); // { success, reason? } ui.selection.getRects(); // ViewportRect[] ui.selection.getRects(captured); // rects of a captured selection ui.selection.getAnchorRect({ placement: 'start' }); // single rect for popovers ui.selection.getAnchorRect({ placement: 'union' }, captured); ``` ### `ui.viewport` Geometry. Browser-only. ```ts theme={null} ui.viewport.getRect({ target: { kind: 'entity', entityType: 'comment', entityId } }); await ui.viewport.scrollIntoView({ target, block: 'center', behavior: 'smooth' }); ui.viewport.getHost(); // painted host element | null ui.viewport.entityAt({ x, y }); // ViewportEntityHit[] ui.viewport.positionAt({ x, y }); // ViewportPositionHit | null ui.viewport.contextAt({ x, y }); // ViewportContext (always returns) ``` ### `ui.toolbar` Aggregate toolbar surface. Mirrors the headless-toolbar shape. ```ts theme={null} ui.toolbar.getSnapshot(); ui.toolbar.subscribe(({ snapshot }) => {}); ui.toolbar.execute(id); // built-ins that take no payload ui.toolbar.execute(id, payload); // built-ins that take a payload ``` `payload` is optional. Pass it for built-ins like `font-size`, `font-family`, and `link` that accept a value; omit it for togglable built-ins like `bold` or `italic`. ### `ui.fonts` Read-only font-family options for custom toolbar UIs. ```ts theme={null} ui.fonts.getOptions(); ui.fonts.observe((snapshot) => {}); ``` Each option has `{ label, value, previewFamily }`. Apply `value` through the `font-family` command. ### `ui.select(selector, equality?)` Raw selector substrate underlying every domain handle. ```ts theme={null} const sub = ui.select((state) => state.selection, shallowEqual); sub.subscribe((selection) => { ... }); ``` ### `ui.destroy()` Tears down every subscription. The provider calls this on unmount. ## Types Imported from `superdoc/ui`. | Type | Shape | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `SuperDocUI` | The controller. | | `SuperDocUIState` | The unified state model. | | `SelectionSlice` | `useSuperDocSelection()` return shape. | | `SelectionCapture` | Output of `ui.selection.capture()`. | | `CommentsSlice` | `useSuperDocComments()` return shape. | | `TrackChangesSlice` | `useSuperDocTrackChanges()` return shape. | | `TrackChangesItem` | `{ id, change }`. | | `DocumentSlice` | `useSuperDocDocument()` return shape. | | `ToolbarSnapshotSlice` | `useSuperDocToolbar()` return shape. | | `FontsHandle` | `ui.fonts` handle shape. | | `FontsSlice` | `ui.fonts` snapshot shape. | | `FontFamilyOption` | `{ label, value, previewFamily }`. | | `UIToolbarCommandState` | Per-command state shape. | | `CustomCommandRegistration` | Input to `ui.commands.register`. | | `CustomCommandRegistrationResult` | Return from `ui.commands.register`. | | `ContextMenuContribution` | The `contextMenu` field on a registration. | | `ContextMenuWhenInput` | Argument to `contextMenu.when({ entities, selection, point?, position?, insideSelection? })`. | | `ContextMenuItem` | Item returned from `ui.commands.getContextMenuItems(input)`. Carries `invoke()` when produced from a `ViewportContext` bundle. | | `SelectionAnchorRectOptions` | `{ placement: 'start' \| 'end' \| 'union' }`. | | `SelectionRestoreResult` | `{ success: true } \| { success: false, reason }`. | | `ScrollIntoViewInput` | Input to `ui.viewport.scrollIntoView`. | | `ViewportRect` | Plain value rectangle. | | `ViewportEntityHit` | `{ type: 'comment' \| 'trackedChange', id }`. | | `ViewportPositionHit` | `{ point: SelectionPoint, target: SelectionTarget }`. | | `ViewportContext` | Bundle returned from `ui.viewport.contextAt({ x, y })`. | For the source of truth, the types ship with the `superdoc` package and are exported alongside the runtime values.