API reference

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.

<SuperDocUIProvider>{children}</SuperDocUIProvider>

`useSetSuperDoc()`

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

const setSuperDoc = useSetSuperDoc();
<SuperDocEditor onReady={({ superdoc }) => setSuperDoc(superdoc)} />;

`useSuperDocUI()`

Returns the controller, or null until ready.

const ui = useSuperDocUI();
ui?.commands.get('bold')?.execute();

`useSuperDocCommand(id)`

Subscribes to one command’s state. See Toolbar and commands.

const bold = useSuperDocCommand('bold');
// { active: boolean; disabled: boolean; value: unknown; source: 'built-in' | 'custom' }

`useSuperDocSelection()`

Returns the live selection slice. See Selection and viewport.

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

`useSuperDocComments()`

Returns the comments slice. See Comments.

const { items, total, activeIds } = useSuperDocComments();

`useSuperDocTrackChanges()`

Returns the tracked-changes slice. See Track changes.

const { items, total, activeId } = useSuperDocTrackChanges();

`useSuperDocDocument()`

Returns the document slice. See Document control.

const { ready, mode, dirty } = useSuperDocDocument();

`useSuperDocToolbar()`

Returns the full toolbar snapshot. Re-renders on any command change. Prefer useSuperDocCommand per button when possible.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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)

Aggregate toolbar surface. Mirrors the headless-toolbar shape.

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.

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.

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.

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Provider and hooks

`<SuperDocUIProvider>`

`useSetSuperDoc()`

`useSuperDocUI()`

`useSuperDocCommand(id)`

`useSuperDocSelection()`

`useSuperDocComments()`

`useSuperDocTrackChanges()`

`useSuperDocDocument()`

`useSuperDocToolbar()`

`useSuperDocFontOptions()`

`useSuperDocFontSizeOptions()`

`useSuperDocSlice(picker, initial)`

`useSuperDocHost()`

Controller handles

`ui.commands`

`ui.comments`

`ui.trackChanges`

`ui.document`

`ui.zoom`

`ui.selection`

`ui.viewport`

`ui.fonts`

`ui.select(selector, equality?)`

`ui.destroy()`

Types

​Provider and hooks

​<SuperDocUIProvider>

​useSetSuperDoc()

​useSuperDocUI()

​useSuperDocCommand(id)

​useSuperDocSelection()

​useSuperDocComments()

​useSuperDocTrackChanges()

​useSuperDocDocument()

​useSuperDocToolbar()

​useSuperDocFontOptions()

​useSuperDocFontSizeOptions()

​useSuperDocSlice(picker, initial)

​useSuperDocHost()

​Controller handles

​ui.commands

​ui.comments

​ui.trackChanges

​ui.document

​ui.zoom

​ui.selection

​ui.viewport

​ui.toolbar

​ui.fonts

​ui.select(selector, equality?)

​ui.destroy()

​Types

Provider and hooks

`<SuperDocUIProvider>`

`useSetSuperDoc()`

`useSuperDocUI()`

`useSuperDocCommand(id)`

`useSuperDocSelection()`

`useSuperDocComments()`

`useSuperDocTrackChanges()`

`useSuperDocDocument()`

`useSuperDocToolbar()`

`useSuperDocFontOptions()`

`useSuperDocFontSizeOptions()`

`useSuperDocSlice(picker, initial)`

`useSuperDocHost()`

Controller handles

`ui.commands`

`ui.comments`

`ui.trackChanges`

`ui.document`

`ui.zoom`

`ui.selection`

`ui.viewport`

`ui.toolbar`

`ui.fonts`

`ui.select(selector, equality?)`

`ui.destroy()`

Types