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

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

Layout regions for button placement

Custom button arrangement by group

Show Example

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

Button names to exclude from toolbar

Custom SVG icons for buttons. See Icon Customization.

Custom tooltips and labels

Available font options in font dropdown. See Font Configuration.

Auto-hide buttons on small screens

Size relative to container instead of window

Custom button definitions. See Custom Buttons.

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

button

Toggle bold (Ctrl+B)

button

Toggle italic (Ctrl+I)

button

Toggle underline (Ctrl+U)

button

Toggle strikethrough

button

Clear all formatting

button

Format painter: copy formatting from selection

Font controls

combobox

Editable font family selector

dropdown

Font size selector (8–96pt)

dropdown

Text color picker

dropdown

Background highlight color picker

The font family control is editable. Type to autocomplete, press Enter to apply, Tab to move to font size, or Esc to revert. The caret opens the full list. If a typed name does not match an option, SuperDoc preserves that custom font name in the document. Load the font on the host page if you want it to render with its real glyphs. The font size control follows the same flow: click the value to type a size, use the caret to open the list, and press Tab to return to the editor.

Paragraph

dropdown

Text alignment (left, center, right, justify)

button

Toggle bullet list

button

Toggle numbered list

button

Decrease indent

button

Increase indent

dropdown

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

dropdown

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

Insert

dropdown

Insert or edit link

button

Upload and insert image

dropdown

Insert table via grid selector

dropdown

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

Tools

button

Undo last action

button

Redo last action

dropdown

Search in document

dropdown

Zoom level (50%–200%)

button

Toggle document ruler

button

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

dropdown

Switch between editing/viewing/suggesting modes

Track changes

button

Accept tracked change at current selection

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();
      }
    }]
  }
}

string

required

'button' or 'dropdown'

string

required

Unique button identifier

Hover text

string

SVG icon string

string

default:"'center'"

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

string | function

required

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

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);
  }
}]

Array

required

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

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);
  }
}]

boolean

default:"false"

Initial active state

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

By default, the font family combobox lists SuperDoc’s bundled defaults plus fonts used by the active document. The list is sorted alphabetically. Choosing a fallback-backed font keeps the Word-facing name in the document. For example, picking Calibri stores and exports Calibri, while the row preview can render with the bundled fallback that actually paints it. Use fonts only when you want to replace the default and document-derived list with your own static options.

Array

Show Font object properties

string

required

Display name shown in the dropdown.

string

required

Value applied to the selected text. Usually the logical font name or a CSS font stack.

number

Font weight

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 }
]

A custom fonts list makes fonts selectable. It does not load font files. To make a custom font render with its real glyphs, load it on your host page via @font-face or a <link> to a font service.

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' }]
  }
}

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

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.

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.

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.

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.

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.

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.

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

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Quick start

Configuration

Available buttons

Text formatting

Font controls

Paragraph

Insert

Tools

Track changes

Custom buttons

Basic button

Toggle button

Icon customization

Font configuration

Loading web fonts

Responsive behavior

Role-based controls

API methods

`getToolbarItemByName`

`getToolbarItemByGroup`

`updateToolbarState`

`setZoom`

`destroy`

`exception`

Full example

Custom Toolbar Example

​Quick start

​Configuration

​Available buttons

​Text formatting

​Font controls

​Paragraph

​Insert

​Tools

​Track changes

​Custom buttons

​Basic button

​Dropdown button

​Toggle button

​Icon customization

​Font configuration

​Loading web fonts

​Responsive behavior

​Role-based controls

​API methods

​getToolbarItemByName

​getToolbarItemByGroup

​updateToolbarState

​setZoom

​destroy

​exception

​Full example

Custom Toolbar Example

Quick start

Configuration

Available buttons

Text formatting

Font controls

Paragraph

Insert

Tools

Track changes

Custom buttons

Basic button

Dropdown button

Toggle button

Icon customization

Font configuration

Loading web fonts

Responsive behavior

Role-based controls

API methods

`getToolbarItemByName`

`getToolbarItemByGroup`

`updateToolbarState`

`setZoom`

`destroy`

`exception`

Full example