> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/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`.

### `<SuperDocUIProvider>`

Holds one controller per editor mount. Wrap your app once.

```tsx theme={null}
<SuperDocUIProvider>{children}</SuperDocUIProvider>
```

### `useSetSuperDoc()`

Returns the setter the editor mount component calls in `onReady`. Most components don't use this directly.

```tsx theme={null}
const setSuperDoc = useSetSuperDoc();
<SuperDocEditor onReady={({ superdoc }) => 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](https://docs.superdoc.dev/editor/custom-ui/toolbar-and-commands.md).

```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](https://docs.superdoc.dev/editor/custom-ui/selection-and-viewport.md).

```ts theme={null}
const selection = useSuperDocSelection();
// { empty, target, selectionTarget, activeMarks, activeCommentIds, activeChangeIds, quotedText }
```

### `useSuperDocComments()`

Returns the comments slice. See [Comments](https://docs.superdoc.dev/editor/custom-ui/comments.md).

```ts theme={null}
const { items, total, activeIds } = useSuperDocComments();
```

### `useSuperDocTrackChanges()`

Returns the tracked-changes slice. See [Track changes](https://docs.superdoc.dev/editor/custom-ui/track-changes.md).

```ts theme={null}
const { items, total, activeId } = useSuperDocTrackChanges();
```

### `useSuperDocDocument()`

Returns the document slice. See [Document control](https://docs.superdoc.dev/editor/custom-ui/document-control.md).

```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<string, UIToolbarCommandState> }
```

### `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.

### `useSuperDocFontSizeOptions()`

Returns the default font-size picker options for custom toolbar UIs.

```ts theme={null}
const sizes = useSuperDocFontSizeOptions();
// [{ label: '8', value: '8pt' }, { label: '9', value: '9pt' }, ...]
```

Use `option.value` with `ui.toolbar.execute('font-size', option.value)`.

### `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.setActive(commentId); // highlight without scrolling or moving selection
ui.comments.setActive(null); // clear active highlight
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.observe(({ reason }) => {});

ui.viewport.getHost(); // painted host element | null
ui.viewport.getScrollContainer(); // scroll 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 picker options for custom toolbar UIs.

```ts theme={null}
ui.fonts.getOptions();
ui.fonts.getSizeOptions();
ui.fonts.observe((snapshot) => {});
```

Family options have `{ label, value, previewFamily }`. Apply `value` through the `font-family` command. Size options have `{ label, value }`. Apply `value` through the `font-size` 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 }`. |
| `FontSizeOption` | `{ label, value }`. |
| `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.