Headless Toolbar

Build your own toolbar UI. SuperDoc provides the state and commands — you render whatever you want.

Using React?

superdoc/headless-toolbar is the framework-agnostic substrate. For new React apps, reach for useSuperDocCommand from superdoc/ui/react instead. It re-renders one button per command (not the whole toolbar) and ships alongside companion hooks for selection, comments, and tracked changes. See Custom UI › Toolbar and commands. superdoc/headless-toolbar stays supported for existing integrations and framework-agnostic toolbar-only use cases. Both paths read from the same internal substrate.

Quick start

import { createHeadlessToolbar } from 'superdoc/headless-toolbar';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
});

const toolbar = createHeadlessToolbar({
  superdoc,
  commands: ['bold', 'italic', 'underline', 'font-size', 'link', 'undo', 'redo'],
});

toolbar.subscribe(({ snapshot }) => {
  renderToolbar(snapshot);
});

toolbar.execute('bold');

Don’t pass toolbar to the SuperDoc constructor. The headless toolbar replaces the built-in UI entirely — no flags needed.

Core concepts

Snapshot

Every time the editor state changes, the toolbar produces a ToolbarSnapshot. Read it to know what your UI should look like.

snapshot.commands['bold']?.active    // true if bold is on
snapshot.commands['bold']?.disabled  // true if the command can't run
snapshot.commands['font-size']?.value // '12pt' — the current value

Execute

Run a command by ID. Returns true if the command executed, false otherwise.

toolbar.execute('bold');
toolbar.execute('font-size', '14pt');
toolbar.execute('text-color', '#ff0000');
toolbar.execute('zoom', 125);

subscribe() fires immediately with the current snapshot, then again on every change. It returns an unsubscribe function.

const unsub = toolbar.subscribe(({ snapshot }) => {
  updateUI(snapshot);
});

// Later:
unsub();

API reference

`createHeadlessToolbar(options)`

Creates a headless toolbar controller bound to a SuperDoc instance.

SuperDoc

required

The SuperDoc instance to bind to.

PublicToolbarItemId[]

Command IDs to track. When omitted, all available commands are tracked.

Returns a HeadlessToolbarController.

`HeadlessToolbarController`

`getSnapshot()`

Returns the current ToolbarSnapshot without subscribing.

const snapshot = toolbar.getSnapshot();
const isBold = snapshot.commands['bold']?.active;

import { createHeadlessToolbar } from 'superdoc/headless-toolbar';

const snapshot = toolbar.getSnapshot();
const isBold = snapshot.commands['bold']?.active;
const isDisabled = snapshot.commands['bold']?.disabled;
const fontSize = snapshot.commands['font-size']?.value;

Registers a listener that receives { snapshot } on every state change. Fires immediately with the current snapshot. Returns an unsubscribe function.

const unsub = toolbar.subscribe(({ snapshot }) => {
  // update your UI
});

import { createHeadlessToolbar } from 'superdoc/headless-toolbar';

const unsub = toolbar.subscribe(({ snapshot }) => {
  const boldActive = snapshot.commands['bold']?.active;
  const fontSizeValue = snapshot.commands['font-size']?.value;
});
unsub();

`execute(id, payload?)`

Runs the command identified by id. Returns true if the command executed, false otherwise.

toolbar.execute('bold');                    // toggle
toolbar.execute('font-size', '14pt');       // set value
toolbar.execute('table-insert', { rows: 3, cols: 4 }); // with object payload

import { createHeadlessToolbar } from 'superdoc/headless-toolbar';

toolbar.execute('bold');
toolbar.execute('italic');
toolbar.execute('underline');
toolbar.execute('strikethrough');
toolbar.execute('font-size', '14pt');
toolbar.execute('font-family', 'Arial, sans-serif');
toolbar.execute('text-color', '#ff0000');
toolbar.execute('highlight-color', '#ffff00');
toolbar.execute('text-align', 'center');
toolbar.execute('line-height', 1.5);
toolbar.execute('bullet-list');
toolbar.execute('numbered-list');
toolbar.execute('indent-increase');
toolbar.execute('indent-decrease');
toolbar.execute('undo');
toolbar.execute('redo');
toolbar.execute('clear-formatting');
toolbar.execute('zoom', 125);
toolbar.execute('document-mode', 'editing');

`destroy()`

Tears down event listeners and clears all subscriptions. Call this when unmounting your toolbar.

toolbar.destroy();

import { createHeadlessToolbar } from 'superdoc/headless-toolbar';

const snapshot = toolbar.getSnapshot();
toolbar.execute('bold');
toolbar.destroy();

`ToolbarSnapshot`

ToolbarContext | null

The current editing context. null when no editor is active.

Partial<Record<PublicToolbarItemId, ToolbarCommandState>>

Map of command IDs to their current state.

`ToolbarCommandState`

boolean

Whether the command is currently active (e.g., bold is on at the cursor position).

boolean

Whether the command can run right now. Disabled when the editor isn’t editable or the command doesn’t apply to the current selection.

unknown

The current value for commands that have one (font size, text color, zoom, etc.). Not present for toggle commands like bold.

`ToolbarContext`

ToolbarTarget

The primary execution surface. Use target.commands for direct command access when execute() doesn’t cover your use case.

'body' | 'header' | 'footer'

Which document surface is currently active.

boolean

Whether the editor is in an editable state.

boolean

Whether the current selection is collapsed (cursor with no range).

Command reference

Snapshot values match the format you pass to execute(). What you read is what you write — no conversion needed.

Text formatting

Command	Payload	`value` in snapshot
`bold`	—	—
`italic`	—	—
`underline`	—	—
`strikethrough`	—	—
`clear-formatting`	—	—
`copy-format`	—	—

Font controls

Command	Payload	`value` in snapshot
`font-size`	`'12pt'`	`'12pt'`
`font-family`	`'Arial, sans-serif'`	`'Arial, sans-serif'`
`text-color`	`'#ff0000'` or `'none'`	`'#ff0000'`
`highlight-color`	`'#ffff00'` or `'none'`	`'#ffff00'`

Paragraph

Command	Payload	`value` in snapshot
`text-align`	`'left'` \| `'center'` \| `'right'` \| `'justify'`	alignment string
`line-height`	number (e.g. `1.5`)	number
`linked-style`	style object from helpers	style ID string
`bullet-list`	—	—
`numbered-list`	—	—
`indent-increase`	—	—
`indent-decrease`	—	—

Insert

Command	Payload	`value` in snapshot
`link`	`{ href: string \| null }`	href string or `null`
`image`	— (opens file picker)	—
`table-insert`	`{ rows: number, cols: number }`	—

Table actions

Command	Payload	`value` in snapshot
`table-add-row-before`	—	—
`table-add-row-after`	—	—
`table-delete-row`	—	—
`table-add-column-before`	—	—
`table-add-column-after`	—	—
`table-delete-column`	—	—
`table-delete`	—	—
`table-merge-cells`	—	—
`table-split-cell`	—	—
`table-remove-borders`	—	—
`table-fix`	—	—

Document

Command	Payload	`value` in snapshot
`undo`	—	—
`redo`	—	—
`ruler`	—	—
`zoom`	number (e.g. `125`)	number
`document-mode`	`'editing'` \| `'suggesting'` \| `'viewing'`	mode string

Track changes

Command	Payload	`value` in snapshot
`track-changes-accept-selection`	—	—
`track-changes-reject-selection`	—	—

Constants

headlessToolbarConstants provides preset option arrays for dropdown-style controls. Each option has { label, value } — use value when calling execute().

import { headlessToolbarConstants } from 'superdoc/headless-toolbar';

const { DEFAULT_FONT_SIZE_OPTIONS } = headlessToolbarConstants;
// [{ label: '8', value: '8pt' }, { label: '9', value: '9pt' }, ...]

import { headlessToolbarConstants } from 'superdoc/headless-toolbar';

const {
  DEFAULT_FONT_FAMILY_OPTIONS,
  DEFAULT_FONT_SIZE_OPTIONS,
  DEFAULT_TEXT_ALIGN_OPTIONS,
  DEFAULT_LINE_HEIGHT_OPTIONS,
  DEFAULT_ZOOM_OPTIONS,
  DEFAULT_DOCUMENT_MODE_OPTIONS,
  DEFAULT_TEXT_COLOR_OPTIONS,
  DEFAULT_HIGHLIGHT_COLOR_OPTIONS,
} = headlessToolbarConstants;

Constant	Contents
`DEFAULT_FONT_FAMILY_OPTIONS`	Aptos, Georgia, Arial, Courier New, Times New Roman
`DEFAULT_FONT_SIZE_OPTIONS`	8pt through 96pt (14 sizes)
`DEFAULT_TEXT_ALIGN_OPTIONS`	left, center, right, justify
`DEFAULT_LINE_HEIGHT_OPTIONS`	1.00, 1.15, 1.50, 2.00, 2.50, 3.00
`DEFAULT_ZOOM_OPTIONS`	50% through 200% (7 levels)
`DEFAULT_DOCUMENT_MODE_OPTIONS`	editing, suggesting, viewing (with descriptions)
`DEFAULT_TEXT_COLOR_OPTIONS`	13 colors including none
`DEFAULT_HIGHLIGHT_COLOR_OPTIONS`	8 colors including none

Helpers

headlessToolbarHelpers provides utilities for advanced workflows.

import { headlessToolbarHelpers } from 'superdoc/headless-toolbar';

Helper	What it does
`getQuickFormatList(editor)`	Returns available paragraph styles (Normal, Heading 1, etc.) for a style dropdown.
`generateLinkedStyleString(style, ...)`	Returns inline CSS for previewing a paragraph style in your UI.
`getFileOpener()`	Returns a function that opens a file picker. Most consumers should use `execute('image')` instead.
`processAndInsertImageFile(...)`	Processes and inserts an image file into the editor. Most consumers should use `execute('image')` instead.

React example

A minimal hook that wires the headless toolbar to React state:

import { useEffect, useRef, useState } from 'react';
import { createHeadlessToolbar } from 'superdoc/headless-toolbar';

function useHeadlessToolbar(superdoc, commands) {
  const [snapshot, setSnapshot] = useState({ context: null, commands: {} });
  const controllerRef = useRef(null);

  useEffect(() => {
    const toolbar = createHeadlessToolbar({ superdoc, commands });
    controllerRef.current = toolbar;
    const unsub = toolbar.subscribe(({ snapshot: s }) => setSnapshot(s));
    return () => { unsub(); toolbar.destroy(); };
  }, [superdoc]);

  return {
    snapshot,
    execute: (id, payload) => controllerRef.current?.execute(id, payload),
  };
}

Then in your component:

function Toolbar({ superdoc }) {
  const { snapshot, execute } = useHeadlessToolbar(superdoc, [
    'bold', 'italic', 'underline', 'font-size',
  ]);

  return (
    <div>
      <button
        onClick={() => execute('bold')}
        data-active={snapshot.commands['bold']?.active}
        disabled={snapshot.commands['bold']?.disabled}
      >
        Bold
      </button>
    </div>
  );
}

Examples

Framework examples

Full examples with React + shadcn, React + MUI, Vue + Vuetify, Svelte, and vanilla JS

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Using React?

Quick start

Core concepts

Snapshot

Execute

API reference

`createHeadlessToolbar(options)`

`HeadlessToolbarController`

`getSnapshot()`

`execute(id, payload?)`

`destroy()`

`ToolbarSnapshot`

`ToolbarCommandState`

`ToolbarContext`

Command reference

Text formatting

Font controls

Paragraph

Insert

Table actions

Document

Track changes

Constants

Helpers

React example

Examples

Framework examples

​Using React?

​Quick start

​Core concepts

​Snapshot

​Execute

​Subscribe

​API reference

​createHeadlessToolbar(options)

​HeadlessToolbarController

​getSnapshot()

​subscribe(listener)

​execute(id, payload?)

​destroy()

​ToolbarSnapshot

​ToolbarCommandState

​ToolbarContext

​Command reference

​Text formatting

​Font controls

​Paragraph

​Insert

​Table actions

​Document

​Track changes

​Constants

​Helpers

​React example

​Examples

Framework examples

Using React?

Quick start

Core concepts

Snapshot

Execute

Subscribe

API reference

`createHeadlessToolbar(options)`

`HeadlessToolbarController`

`getSnapshot()`

`subscribe(listener)`

`execute(id, payload?)`

`destroy()`

`ToolbarSnapshot`

`ToolbarCommandState`

`ToolbarContext`

Command reference

Text formatting

Font controls

Paragraph

Insert

Table actions

Document

Track changes

Constants

Helpers

React example

Examples