Toolbar

SuperDoc ships with a ready-made toolbar. Point it at a container, and you get formatting controls, font pickers, and document actions out of the box.

Want full control over the toolbar UI? On React, use Custom UI: typed hooks (useSuperDocCommand), per-command re-renders, custom commands. For non-React stacks, use the headless toolbar.

Quick start

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

Configuration

modules.toolbar.selector · string

CSS selector for the toolbar container (e.g. '#toolbar'). Must be a string selector, not a DOM element reference.

modules.toolbar.toolbarGroups · string[] · default: "['left', 'center', 'right']"

Layout regions for button placement

modules.toolbar.groups · Object

Custom button arrangement by group

Show Example

groups: {
  left: ['undo', 'redo'],
  center: ['bold', 'italic', 'underline'],
  right: ['documentMode', 'export']
}

modules.toolbar.excludeItems · string[] · default: "[]"

Button names to exclude from toolbar

modules.toolbar.icons · Object · default: "{}"

Custom SVG icons for buttons. See Icon Customization.

modules.toolbar.texts · Object · default: "{}"

Custom tooltips and labels

modules.toolbar.fonts · Array · default: "[]"

Available font options in font dropdown. See Font Configuration.

modules.toolbar.hideButtons · boolean · default: "true"

Auto-hide buttons on small screens

modules.toolbar.responsiveToContainer · boolean · default: "false"

Size relative to container instead of window

modules.toolbar.customButtons · Array · default: "[]"

Custom button definitions. See Custom Buttons.

modules.toolbar.showFormattingMarksButton · boolean · default: "false"

Show the formatting marks (pilcrow) button in the toolbar. Off by default. Distinct from layoutEngineOptions.showFormattingMarks, which controls whether the marks render in the document.

Available buttons

Use button names with excludeItems, groups, and icons configuration.

Text formatting

bold · button

Toggle bold (Ctrl+B)

italic · button

Toggle italic (Ctrl+I)

underline · button

Toggle underline (Ctrl+U)

strike · button

Toggle strikethrough

clearFormatting · button

Clear all formatting

copyFormat · button

Format painter: copy formatting from selection

Font controls

fontFamily · dropdown

Font family selector

fontSize · dropdown

Font size selector (8–96pt)

color · dropdown

Text color picker

highlight · dropdown

Background highlight color picker

Paragraph

textAlign · dropdown

Text alignment (left, center, right, justify)

list · button

Toggle bullet list

numberedlist · button

Toggle numbered list

indentleft · button

Decrease indent

indentright · button

Increase indent

lineHeight · dropdown

Line height selector (1, 1.15, 1.5, 2, 2.5, 3)

linkedStyles · dropdown

Quick paragraph styles (Normal, Heading 1, etc.)

Insert

link · dropdown

Insert or edit link

image · button

Upload and insert image

table · dropdown

Insert table via grid selector

tableActions · dropdown

Table editing actions (add/delete rows/columns, merge/split cells, etc.)

Tools

undo · button

Undo last action

redo · button

Redo last action

search · dropdown

Search in document

zoom · dropdown

Zoom level (50%–200%)

ruler · button

Toggle document ruler

formattingMarks · button

Toggle formatting marks (pilcrow) display. Hidden by default; enable with modules.toolbar.showFormattingMarksButton: true.

documentMode · dropdown

Switch between editing/viewing/suggesting modes

Track changes

acceptTrackedChangeBySelection · button

Accept tracked change at current selection

rejectTrackedChangeOnSelection · button

Reject tracked change at current selection

Custom buttons

Basic button

modules: {
  toolbar: {
    customButtons: [{
      type: 'button',
      name: 'myButton',
      tooltip: 'My Custom Button',
      icon: '<svg>...</svg>',
      group: 'center',
      command: ({ item, argument, option }) => {
        superdoc.activeEditor.commands.myCommand();
      }
    }]
  }
}

type · string · required

'button' or 'dropdown'

name · string · required

Unique button identifier

tooltip · string

Hover text

icon · string

SVG icon string

group · string · default: "'center'"

Layout group: 'left', 'center', or 'right'

command · string | function · required

Command name or handler function receiving { item, argument, option }

Dropdown button

customButtons: [{
  type: 'dropdown',
  name: 'templates',
  tooltip: 'Insert Template',
  icon: templateIcon,
  hasCaret: true,
  options: [
    { label: 'Contract', key: 'contract' },
    { label: 'Invoice', key: 'invoice' }
  ],
  command: ({ option }) => {
    if (option) loadTemplate(option.key);
  }
}]

options · Array · required

Dropdown items, each with label (display text), key (value), and optional icon

hasCaret · boolean · default: "true"

Show dropdown arrow

Toggle button

customButtons: [{
  type: 'button',
  name: 'darkMode',
  tooltip: 'Toggle Dark Mode',
  icon: moonIcon,
  activeIcon: sunIcon,
  active: false,
  command: ({ item }) => {
    const isActive = !item.active.value;
    item.active.value = isActive;
    setDarkMode(isActive);
  }
}]

active · boolean · default: "false"

Initial active state

activeIcon · string

Icon when active

Icon customization

modules: {
  toolbar: {
    icons: {
      bold: '<svg viewBox="0 0 24 24">...</svg>',
      italic: '<svg viewBox="0 0 24 24">...</svg>',
      // Function for dynamic icons
      darkMode: () => isDark ? sunIcon : moonIcon
    }
  }
}

Icons should be 24x24 viewBox SVGs with fill="currentColor" for proper theming

Font configuration

The toolbar dropdown lists only what you register in fonts. Imported documents don’t auto-populate the list: if a user opens a .docx that uses Cambria and Cambria isn’t registered, the current-selection indicator shows “Cambria” but the user can’t pick it from the dropdown.

fonts · Array

Show Font object properties

label · string · required

Display name shown in the dropdown, and the value applied to the selected text. Must match the first family name in key: otherwise the dropdown won’t light up the current font when the cursor is inside a run that uses it.

key · string · required

Stable identity for the option. Also used as the row’s preview font-family so each row renders in its own typeface. Typically a full CSS stack (e.g. 'Cambria, serif').

fontWeight · number

Font weight

props · object

Optional. Overrides per-row rendering. Use props.style.fontFamily to preview the row in a different font than key.

fonts: [
  { label: 'Arial', key: 'Arial, sans-serif' },
  { label: 'Times New Roman', key: 'Times New Roman, serif' },
  { label: 'Brand Font', key: 'BrandFont, sans-serif', fontWeight: 400 }
]

Registering a font in fonts makes it selectable. It doesn’t load any font files. To make the font actually render with its real glyphs, load it on your host page via @font-face or a <link> to a font service. Fonts the browser can’t find fall back to the CSS generic.

Loading web fonts

Any font loaded on your host page is available inside the editor. Load it, then register it in fonts:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter&display=swap" />

modules: {
  toolbar: {
    fonts: [{ label: 'Inter', key: 'Inter, sans-serif' }]
  }
}

Substituting Microsoft Office fonts

Most .docx files use Cambria, Calibri, or Aptos: fonts bundled with Word on desktop but not present in browsers. Google hosts free metric-compatible replacements:

Office font	Free substitute	Notes
Calibri	Carlito	Sans-serif, metric-identical: designed as a direct drop-in
Cambria	Tinos or Gelasio	Serif
Aptos	Carlito or Inter	Sans-serif: no free metric-identical match exists yet

Download the .woff2 files from Google Fonts, host them with your app, and alias each substitute to the original Word name via @font-face. The browser will then render real Carlito/Tinos glyphs whenever the document asks for Calibri/Cambria: no document or SuperDoc changes needed.

<style>
  @font-face {
    font-family: 'Calibri';
    src: url('/fonts/Carlito-Regular.woff2') format('woff2');
    font-display: swap;
  }
  @font-face {
    font-family: 'Cambria';
    src: url('/fonts/Tinos-Regular.woff2') format('woff2');
    font-display: swap;
  }
</style>

Self-hosting the .woff2 files is more reliable than linking to Google Fonts CDN URLs directly: those URLs change when Google updates a font version.

Responsive behavior

The toolbar adapts at these widths:

Breakpoint	Width	Behavior
XL	1410px+	All buttons visible
LG	1280px+	Hides styles, format painter
MD	1024px+	Hides separators
SM	768px+	Hides zoom, font, redo
XS	Under 768px	Shows overflow menu

Use responsiveToContainer: true to size based on the toolbar container instead of the window.

Role-based controls

The toolbar automatically adapts based on the user’s role:

Role	Available Controls
viewer	Zoom, search, print, export only
suggester	Track changes enabled, formatting available
editor	Full access to all controls

API methods

Usage

const toolbar = superdoc.toolbar;

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    const toolbar = superdoc.toolbar;
  },
});

getToolbarItemByName

Get a toolbar item by its name.

Usage

const boldBtn = toolbar.getToolbarItemByName('bold');
boldBtn.active.value;    // boolean
boldBtn.disabled.value;  // boolean

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    const toolbar = superdoc.toolbar;
    const boldBtn = toolbar.getToolbarItemByName('bold');
    boldBtn.active.value;    // boolean
    boldBtn.disabled.value;  // boolean
  },
});

getToolbarItemByGroup

Get all toolbar items in a layout group.

Usage

const leftItems = toolbar.getToolbarItemByGroup('left');

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    const toolbar = superdoc.toolbar;
    const leftItems = toolbar.getToolbarItemByGroup('left');
  },
});

updateToolbarState

Refresh all button states based on the current editor state.

Usage

toolbar.updateToolbarState();

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    const toolbar = superdoc.toolbar;
    toolbar.updateToolbarState();
  },
});

setZoom

Set the editor zoom level programmatically through the owning SuperDoc instance.

Usage

superdoc.setZoom(150); // 150%

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    superdoc.setZoom(150); // 150%
  },
});

destroy

Clean up toolbar resources and event listeners.

Usage

toolbar.destroy();

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    const toolbar = superdoc.toolbar;
    toolbar.destroy();
  },
});

exception

Fired when an error occurs during a toolbar action.

Usage

toolbar.on('exception', ({ error, editor, originalError }) => {
  console.error('Toolbar error:', error);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  toolbar: '#toolbar',
  onReady: (superdoc) => {
    const toolbar = superdoc.toolbar;
    toolbar.on('exception', ({ error, editor, originalError }) => {
      console.error('Toolbar error:', error);
    });
  },
});

Full example

Custom Toolbar Example

Runnable example: custom button groups, excluded items, and a custom clear-formatting button