Skip to main content
useSuperDocCommand(id) subscribes one button to one command. The component re-renders when that command flips active or disabled, never on every editor change. ui.commands.get(id)?.execute(payload?) runs the command.

​
A single button

import { useSuperDocCommand, useSuperDocUI } from 'superdoc/ui/react';

export function BoldButton() {
  const ui = useSuperDocUI();
  const bold = useSuperDocCommand('bold');

  return (
    <button
      className={bold.active ? 'active' : ''}
      disabled={bold.disabled}
      onClick={() => ui?.commands.get('bold')?.execute()}
    >
      B
    </button>
  );
}

​
A row of buttons

Build a static config and map. Each <ToolbarButton> subscribes to its own command, so unrelated state changes don’t re-render the row. 
import { useSuperDocCommand, useSuperDocUI } from 'superdoc/ui/react';

const TEXT_BUTTONS = [
  { id: 'bold', label: 'B', title: 'Bold (⌘B)' },
  { id: 'italic', label: 'I', title: 'Italic (⌘I)' },
  { id: 'underline', label: 'U', title: 'Underline (⌘U)' },
];

export function Toolbar() {
  return (
    <div role='toolbar'>
      {TEXT_BUTTONS.map((b) => (
        <ToolbarButton key={b.id} id={b.id} label={b.label} title={b.title} />
      ))}
    </div>
  );
}

function ToolbarButton({ id, label, title }: { id: string; label: string; title: string }) {
  const ui = useSuperDocUI();
  const cmd = useSuperDocCommand(id);

  return (
    <button
      className={cmd.active ? 'active' : ''}
      disabled={cmd.disabled}
      title={title}
      onClick={() => ui?.commands.get(id)?.execute()}
    >
      {label}
    </button>
  );
}
See the configurable toolbar example for a runnable vanilla version: a config-driven button row that subscribes per-id and reads disabled / active straight from the controller.

​
Commands with payloads

Some commands take a value. Pass it to execute(). 
import { useSuperDocCommand, useSuperDocFontSizeOptions, useSuperDocUI } from 'superdoc/ui/react';

function FontSizePicker() {
  const ui = useSuperDocUI();
  const size = useSuperDocCommand('font-size');
  const options = useSuperDocFontSizeOptions();

  return (
    <select
      value={typeof size.value === 'string' ? size.value : ''}
      disabled={size.disabled}
      onChange={(e) => ui?.commands.get('font-size')?.execute(e.target.value)}
    >
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
}
useSuperDocCommand('font-size').value is the current value for the active selection. The same pattern works for font-family, text-color, and other value commands.

​
Font family picker

Use useSuperDocFontOptions() for a custom font dropdown. It returns the fonts SuperDoc can render plus fonts used by the active document, sorted alphabetically. Without a configured font pack that is the conservative baseline; configure the pack (@superdoc-dev/fonts, or fonts.assetBaseUrl) and it returns the full set, minus anything curated with createSuperDocFonts. label is what you show. value is what you pass to the font-family command. previewFamily is only for rendering the option row. 
import { useEffect, useRef, useState } from 'react';
import type { SelectionCapture } from 'superdoc/ui';
import { useSuperDocCommand, useSuperDocFontOptions, useSuperDocUI } from 'superdoc/ui/react';

function firstFontName(value: unknown) {
  return typeof value === 'string'
    ? value
        .split(',')[0]
        ?.trim()
        .replace(/^["']|["']$/g, '') || ''
    : '';
}

function FontFamilyPicker() {
  const ui = useSuperDocUI();
  const font = useSuperDocCommand('font-family');
  const options = useSuperDocFontOptions();
  const capturedSelection = useRef<SelectionCapture | null>(null);
  const menuRef = useRef<HTMLDivElement | null>(null);
  const [open, setOpen] = useState(false);
  const current = firstFontName(font.value).toLowerCase();
  const selectedOption =
    options.find((option) => {
      return (
        firstFontName(option.value).toLowerCase() === current ||
        firstFontName(option.previewFamily).toLowerCase() === current
      );
    }) ?? null;

  useEffect(() => {
    if (!open) return;
    const close = (event: MouseEvent) => {
      if (!menuRef.current?.contains(event.target as Node | null)) setOpen(false);
    };
    document.addEventListener('mousedown', close);
    return () => document.removeEventListener('mousedown', close);
  }, [open]);

  const rememberSelection = () => {
    const capture = ui?.selection.capture();
    if (capture) capturedSelection.current = capture;
  };

  const applyFont = (value: string) => {
    if (!ui) return;
    if (capturedSelection.current) {
      ui.selection.restore(capturedSelection.current);
      capturedSelection.current = null;
    }
    setOpen(false);
    ui.toolbar.execute('font-family', value);
  };

  return (
    <div ref={menuRef}>
      <button
        type='button'
        disabled={font.disabled}
        onMouseDown={(event) => {
          event.preventDefault();
          rememberSelection();
        }}
        onClick={() => setOpen((value) => !value)}
      >
        {selectedOption?.label ?? 'Font'}
      </button>
      {open && (
        <div role='listbox'>
          {options.map((option) => (
            <button
              key={option.value}
              type='button'
              role='option'
              aria-selected={option.value === selectedOption?.value}
              style={{ fontFamily: option.previewFamily }}
              onMouseDown={(event) => {
                event.preventDefault();
                rememberSelection();
              }}
              onClick={() => applyFont(option.value)}
            >
              {option.label}
            </button>
          ))}
        </div>
      )}
    </div>
  );
}
When a user picks Calibri, SuperDoc stores and exports Calibri. The preview can render with the bundled fallback that actually paints it. Avoid native selects for this control. They take browser focus and visually clear the editor selection while the menu is open.

​
Interactive UI vs explicit document edits

Use command execution for a toolbar. It preserves the active editor selection and matches the built-in toolbar behavior. 
ui?.toolbar.execute('font-family', option.value);
ui?.toolbar.execute('font-size', option.value);
Use the Document API when your code already has a target and wants one explicit document mutation. Batch related formatting in one format.apply call. 
editor.doc.format.apply({
  target,
  inline: {
    fontFamily: 'Inter',
    fontSize: 15,
  },
});

​
What the hook returns

FieldTypeMeaning
activebooleanThe command is “on” for the current selection (cursor is inside bold text).
disabledbooleanThe command can’t run right now (no selection, wrong document mode).
valueunknownThe command’s current value when applicable (font name, size, color).
source'built-in' | 'custom'Where the command came from.
useSuperDocCommand returns a fallback { active: false, disabled: true, source: 'built-in' } while the editor is initializing, so your buttons render disabled with no flicker.

​
Built-in command ids

Common ids you’ll wire to buttons:
GroupIds
Textbold, italic, underline, strikethrough
Inlinelink, font-family, font-size, text-color, highlight-color
Layouttext-align, line-height, indent-increase, indent-decrease
Listsbullet-list, numbered-list
Stylelinked-style, clear-formatting, copy-format
Historyundo, redo
Tracked changestrack-changes-accept-selection, track-changes-reject-selection
Viewruler, zoom, zoom-fit-width, document-mode
Tablestable-insert, table-add-row-before, table-add-row-after, table-delete-row, table-add-column-before, table-add-column-after, table-delete-column, table-merge-cells, table-split-cell, table-delete
Insertimage
PublicToolbarItemId in superdoc/ui is the source of truth. Anything you can pass to createHeadlessToolbar({ commands }) works as a useSuperDocCommand id.

​
Aggregate snapshots

Need every command in one render pass (e.g. you generate the toolbar from the active context)? Subscribe to the whole toolbar slice. 
import { useSuperDocToolbar } from 'superdoc/ui/react';

function ContextualToolbar() {
  const toolbar = useSuperDocToolbar();
  const ids = Object.keys(toolbar.commands);

  return <div>{ids.length} commands available</div>;
}
Prefer useSuperDocCommand per button when you can. useSuperDocToolbar re-renders on any command change.

​
Trade-offs

  • The hook subscribes per-id. Reusing a button component with different ids is fine: the subscription resets when id changes.
  • Built-in command state is derived from the active editor. If your provider sits above multiple editors, the ids you pass are scoped to whichever editor reported ready last.
  • Custom commands you registered with ui.commands.register work with the same hook.