Customize actions and the toolbar

After you load Nutrient Document Authoring SDK, use the Actions API and Toolbar API to customize editor behavior and toolbar layout. If you haven’t set up the SDK, refer to the getting started guide.

Use actions to:

• Customize built-in editor commands
• Add custom commands
• Define keyboard shortcuts
• Enable or disable commands at runtime

Use toolbar configuration to:

• Remove built-in toolbar items
• Create a smaller toolbar for focused editing
• Add buttons that trigger custom actions

When you customize the toolbar, start from defaultToolbarConfig when possible. This keeps new built-in controls available after SDK upgrades. Examples include the header and footer controls in the 1.17.0 changelog. Another is the built-in Find toolbar item in the 1.20.0 release notes. The 1.22.0 release notes cover the table of contents and line spacing controls.

The example code omits error handling, so add error handling before you use this code in production.

Register actions when creating the editor

Use UIOptions.actions to set the first action list, and start from defaultActions to keep the standard editor commands:

import { defaultActions } from '@nutrient-sdk/document-authoring';

const editor = await docAuthSystem.createEditor(
  document.getElementById('editor'),
  {
    ui: {
      actions: [
        ...defaultActions,
        {
          id: 'custom.insert-signature',
          label: 'Insert Signature',
          shortcuts: ['Mod+Shift+S'],
          handler: () => {
            editor.insertContentAtCursor({
              content: '\n\nBest regards,\nJane Doe',
            });
          },
        },
      ],
    },
  },
);

Built-in actions can omit handler and use the default SDK behavior. Custom actions must include a handler.

Replace or update actions at runtime

Use editor.setActions() to replace the current action list:

import { defaultActions } from '@nutrient-sdk/document-authoring';

editor.setActions([
  ...defaultActions,
  {
    id: 'custom.insert-date',
    label: "Insert Today's Date",
    isEnabled: () => editor.hasActiveCursor(),
    handler: () => {
      editor.insertContentAtCursor({
        content: new Date().toLocaleDateString(),
      });
    },
  },
]);

Read selected content and insert content at the cursor

Use editor.getSelectionContent() to read the current selection. Use editor.insertContentAtCursor() to insert content at the cursor or replace an active range selection:

const selectedText = editor.getSelectionContent({ format: 'text' });

if (selectedText !== null) {
  console.log('Selected text:', selectedText);
}

if (editor.hasActiveCursor()) {
  editor.insertContentAtCursor({
    content: 'Inserted from a custom workflow',
  });
}

Use a fragment instead of plain text when you need to preserve formatting and structure. format: 'text' returns only the characters. format: 'fragment' returns a structured object that you can pass back to insertContentAtCursor():

const fragment = editor.getSelectionContent({ format: 'fragment' });

if (fragment) {
  // A fragment is opaque, JSON-serializable data: Capture it, store it, or
  // transform it. Then insert it back with its formatting intact.
  editor.insertContentAtCursor({ format: 'fragment', content: fragment });
}

getSelectionContent() returns null when nothing is selected — a collapsed caret doesn’t count as a selection. Use hasActiveCursor() to check for a cursor.

Treat the fragment as opaque data. You can serialize it and roundtrip it, but don’t rely on its internal shape.

Inserting a malformed fragment throws a typed error; refer to the error handling guide to catch it.

To keep external controls synchronized with the selection, subscribe to selection.change. Refer to the react to selection changes guide for the selection event.

Customize a built-in action

Relabel a built-in action or provide a custom handler. This example changes the export action label.

import { defaultActions } from '@nutrient-sdk/document-authoring';

editor.setActions([
  ...defaultActions.filter(({ id }) => id !== 'document.export-pdf'),
  {
    id: 'document.export-pdf',
    label: 'Download PDF',
  },
]);

This action keeps its default export behavior and uses a custom label.

Configure the command palette

The command palette uses the built-in view.open-command-palette action and the command-palette toolbar item. Users open it with Control/Command-/ or with the toolbar button.

You can relabel, rebind, move, or remove it like any other built-in action or toolbar item. Use the Actions API and Toolbar API for these changes:

import { defaultActions } from '@nutrient-sdk/document-authoring';

editor.setActions([
  ...defaultActions.filter(({ id }) => id !== 'view.open-command-palette'),
  {
    id: 'view.open-command-palette',
    label: 'Search commands',
    shortcuts: ['Mod+Shift+K'],
  },
]);

Configure the Find action and toolbar item

The editor includes a built-in Find bar. Users open it with Control/Command-F. The action stays hidden from the command palette.

You can relabel, rebind, or remove view.find like any other built-in action:

import { defaultActions } from '@nutrient-sdk/document-authoring';

editor.setActions([
  ...defaultActions.filter(({ id }) => id !== 'view.find'),
  {
    id: 'view.find',
    label: 'Search document',
    shortcuts: ['Mod+Shift+F'],
  },
]);

If you leave view.find out of the action list, the shortcut no longer opens the bar, but editor.find.open() still works.

Starting with Document Authoring SDK 1.20.0, you can add the built-in find item to a custom toolbar configuration. For details, refer to the 1.20.0 release notes.

import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';

editor.setToolbarConfig({
  ...defaultToolbarConfig,
  items: [
    ...defaultToolbarConfig.items,
    { type: 'separator', id: 'sep-find' },
    { type: 'built-in', id: 'find', builtInType: 'find' },
  ],
});

For the Find bar and the editor.find programmatic API, refer to the Find interface guide.

Configure the toolbar when creating the editor

Use UIOptions.toolbar to set the first toolbar layout, and start from defaultToolbarConfig to keep most standard toolbar items:

import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';

const editor = await docAuthSystem.createEditor(
  document.getElementById('editor'),
  {
    ui: {
      toolbar: {
        ...defaultToolbarConfig,
        items: defaultToolbarConfig.items.filter(
          (item) => item.id !== 'download-menu',
        ),
      },
    },
  },
);

Build a minimal toolbar

Use built-in items and separators to create a smaller toolbar for focused editing. A minimal toolbar replaces the default toolbar.

A minimal toolbar can hide built-in controls that users need. These include controls for page layout, headers and footers, image and shape wrapping, table of contents insertion, and line spacing. Add those controls when your workflow requires them.

editor.setToolbarConfig({
  items: [
    { type: 'built-in', id: 'undo', builtInType: 'undo' },
    { type: 'built-in', id: 'redo', builtInType: 'redo' },
    { type: 'separator', id: 'sep-1' },
    { type: 'built-in', id: 'bold', builtInType: 'bold' },
    { type: 'built-in', id: 'italic', builtInType: 'italic' },
    { type: 'built-in', id: 'underline', builtInType: 'underline' },
  ],
});

Add a custom action to the toolbar

Toolbar action items reference action IDs, so register the action before you add it to the toolbar:

import {
  defaultActions,
  defaultToolbarConfig,
} from '@nutrient-sdk/document-authoring';

editor.setActions([
  ...defaultActions,
  {
    id: 'custom.save-document',
    label: 'Save',
    handler: async () => {
      const doc = await editor.currentDocument().saveDocument();
      await fetch('/api/save', {
        method: 'POST',
        body: JSON.stringify(doc),
      });
    },
  },
]);

editor.setToolbarConfig({
  ...defaultToolbarConfig,
  items: [
    ...defaultToolbarConfig.items,
    { type: 'separator', id: 'sep-custom' },
    { type: 'action', id: 'save-btn', actionId: 'custom.save-document' },
  ],
});

Editor appearance

Document Authoring doesn’t currently expose a dark-mode configuration for the editor UI. Style the surrounding application separately, and use the Actions and Toolbar APIs to customize editor workflows and available commands.

Learn more

Use these references for API details and related customization guides.

• Document Authoring API reference