CustomAction>= v1.9.0

CustomAction:

{
  id: string;
  label: string;
  description?: string;
  capabilities?: readonly ActionCapability[];
  shortcuts?: string[];
  icon?: string;
  isEnabled?: () => boolean;
  handler: (args: any[]) => void | Promise<void>;
}

Custom actions allow you to add your own functionality to the editor. Unlike BuiltInAction, custom actions must provide a handler function.

If capabilities is omitted, a custom action counts as document.change, so it can’t run in view mode. This keeps existing integrations working as before. To let a custom action run in view mode, give it only capabilities that view mode allows, such as external.open.

Example

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

// Add a custom action with keyboard shortcut
editor.setActions([
  ...defaultActions,
  {
    id: 'custom.insert-signature',
    label: 'Insert Signature',
    shortcuts: ['Mod+Shift+S'],
    handler: () => {
      editor.insertTextAtCursor('\n\nBest regards,\nJohn Doe');
    },
  },
]);

// Add a custom action with custom icon
editor.setActions([
  ...defaultActions,
  {
    id: 'custom.save',
    label: 'Save Document',
    icon: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiPi4uLjwvc3ZnPg==',
    handler: async () => {
      const doc = await editor.currentDocument().saveDocument();
      await fetch('/api/save', {
        method: 'POST',
        body: JSON.stringify(doc),
      });
    },
  },
]);

// Add a conditional action (disabled when no cursor/selection)
editor.setActions([
  ...defaultActions,
  {
    id: 'custom.insert-date',
    label: "Insert Today's Date",
    isEnabled: () => editor.hasActiveCursor(),
    handler: () => {
      const date = new Date().toLocaleDateString();
      editor.insertTextAtCursor(date);
    },
  },
]);

// Allow a read-only custom action to run in view mode
editor.setActions([
  ...defaultActions,
  {
    id: 'custom.open-help',
    label: 'Open Help',
    capabilities: ['external.open'],
    handler: () => {
      window.open('/help', '_blank');
    },
  },
]);

See

BuiltInAction for built-in actions with default implementations.
ToolbarActionItem for adding custom actions to the toolbar.

Properties

id

id: string

Unique identifier for this action (must not be a BuiltInActionId)

label

label: string

Text shown for the action in the command palette and on ToolbarActionItem buttons. The editor doesn’t translate it and shows the same text whatever the locale.

description?

optional description: string

capabilities?

optional capabilities: readonly ActionCapability[]

What kind of change the action makes, which decides the editor modes it can run in. Defaults to document.change. setActions() throws on values that are not an ActionCapability.

shortcuts?

optional shortcuts: string[]

Keyboard shortcuts for the action. Use “Mod” as the primary modifier key - it will be automatically resolved to:

“Ctrl” on Windows/Linux
”⌘” (Command) on Mac

Examples:

“Mod+B” becomes “Ctrl+B” on Windows, “⌘B” on Mac
“Mod+Shift+P” becomes “Ctrl+Shift+P” on Windows, ”⌘⇧P” on Mac

icon?

optional icon: string

Icon as data URI (e.g., data:image/svg+xml;base64,… or data:image/png;base64,…). Only data:image/ URIs are allowed for security.

isEnabled()?

optional isEnabled: () => boolean

Optional function to determine if this action should be enabled

Returns

boolean

handler()

handler: (…args) => void | Promise<void>

Handler function that executes when the action is triggered (required for custom actions)

Parameters

args

…any[]

Returns

void | Promise<void>