> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!TIP]
>
> Want full control over the toolbar UI? On React, use [Custom UI](https://docs.superdoc.dev/editor/custom-ui/toolbar-and-commands.md): typed hooks (`useSuperDocCommand`), per-command re-renders, custom commands. For non-React stacks, use the [headless toolbar](https://docs.superdoc.dev/advanced/headless-toolbar).

## Quick start

```javascript theme={null}
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

**Example**

```javascript theme={null}
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](#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](#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](#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** `combobox`

Editable font family selector

**fontSize** `dropdown`

Font size selector (8–96pt)

**color** `dropdown`

Text color picker

**highlight** `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

**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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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
    }
  }
}
```

> [!WARNING]
>
> 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.

**fonts** `Array`

**Font object properties**

**label** `string` *required*

Display name shown in the dropdown.

**key** `string` *required*

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

**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`.

```javascript theme={null}
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 }
]
```

> [!NOTE]
>
> 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`:

```html theme={null}
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter&display=swap" />
```

```javascript theme={null}
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

```javascript Usage theme={null}
const toolbar = superdoc.toolbar;
```

```javascript Full Example theme={null}
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.

```javascript Usage theme={null}
const boldBtn = toolbar.getToolbarItemByName('bold');
boldBtn.active.value;    // boolean
boldBtn.disabled.value;  // boolean
```

```javascript Full Example theme={null}
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.

```javascript Usage theme={null}
const leftItems = toolbar.getToolbarItemByGroup('left');
```

```javascript Full Example theme={null}
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.

```javascript Usage theme={null}
toolbar.updateToolbarState();
```

```javascript Full Example theme={null}
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.

```javascript Usage theme={null}
superdoc.setZoom(150); // 150%
```

```javascript Full Example theme={null}
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.

```javascript Usage theme={null}
toolbar.destroy();
```

```javascript Full Example theme={null}
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.

```javascript Usage theme={null}
toolbar.on('exception', ({ error, editor, originalError }) => {
  console.error('Toolbar error:', error);
});
```

```javascript Full Example theme={null}
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

> [card] [Custom Toolbar Example](https://go.superdoc.dev/toolbar)
>
> Runnable example: custom button groups, excluded items, and a custom clear-formatting button


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.