Toolbar

The toolbar provides a customizable UI for document editing with support for custom buttons, responsive layouts, and role-based controls.

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.

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

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

fonts · Array

Show Font object properties

label · string · required

Display name

key · string · required

Font-family CSS value

fontWeight · number

Font weight

SuperDoc does not load fonts automatically. Custom fonts from imported DOCX files will display in the toolbar, but won’t be selectable unless you load them in your application (via CSS @font-face, Google Fonts, etc.) and add them to the fonts array.

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

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.

Usage

toolbar.setZoom(150); // 150%

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

Events

superdoc-command

Fired when a SuperDoc-level command is executed (zoom, document mode).

Usage

toolbar.on('superdoc-command', ({ item, argument }) => {
  console.log(`Command: ${item.command}, arg: ${argument}`);
});

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('superdoc-command', ({ item, argument }) => {
      console.log(`Command: ${item.command}, arg: ${argument}`);
    });
  },
});

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