Module API: Custom Toolbar Buttons in Lumen Editor

Modules are the building blocks of the Lumen Editor toolbar. Every button you see — bold, heading, image insert, undo — is a module: a plain object that describes the button’s appearance and what happens when it is clicked. You can access the 17 built-in modules, override them, reorder them, and add your own using the same interface.

`EditorModule` Interface

Every module — built-in or custom — implements the EditorModule interface:

interface EditorModule {
  name: string;
  group: string;
  icon: string;
  label: string;
  exec: (editor: Editor) => void;
}

string

required

A unique command identifier for the module. This is the string you reference in the toolbar option array to place the button. It must be unique across all registered modules.

string

required

The logical category of the command. Accepted values are 'inline', 'block', 'history', and 'insert'. The group does not affect rendering — it is metadata for your own organisation and for any third-party plugins that inspect the module registry.

string

required

An HTML string rendered as the inner content of the toolbar button. You can use an SVG literal, a Unicode character, an <img> tag, or any valid HTML fragment. The string is injected via innerHTML, so keep it trusted.

string

required

The tooltip text displayed on hover and used as the button’s aria-label. Keep labels short and descriptive — they are the primary accessibility affordance for the toolbar button.

(editor: Editor) => void

required

The function called when the toolbar button is clicked. Receives the live Editor instance so you can call any public method — setHTML(), getHTML(), on(), focus(), etc. — or interact with document.execCommand for low-level formatting.

Accessing Built-in Modules

Lumen Editor exports all built-in modules as a keyed record object:

import { Editor, modules } from 'lumen-editor';
// modules: Record<string, EditorModule>

Each built-in module is accessible by its name as a key:

console.log(modules.bold);
// {
//   name: 'bold',
//   group: 'inline',
//   icon: '<svg …>…</svg>',
//   label: 'Bold',
//   exec: [Function],
// }

You can spread modules into your own array, override individual entries, or pick specific ones to keep the toolbar minimal:

// Use only a subset of built-ins
const minimalModules = [
  modules.bold,
  modules.italic,
  modules.link,
  modules.undo,
  modules.redo,
];

Built-in Module Names

All 17 built-in modules and their groups:

Name	Group
`undo`	`history`
`redo`	`history`
`bold`	`inline`
`italic`	`inline`
`underline`	`inline`
`strikethrough`	`inline`
`h1`	`block`
`h2`	`block`
`h3`	`block`
`paragraph`	`block`
`ul`	`block`
`ol`	`block`
`blockquote`	`block`
`code`	`block`
`link`	`insert`
`image`	`insert`
`html`	`insert`

Registering Custom Modules

To add a custom module, include it in the modules array alongside the built-ins, and add its name to the toolbar layout. The example below adds a Highlight button that applies a yellow background to selected text:

import { Editor, modules } from 'lumen-editor';
import 'lumen-editor/theme.css';

const highlightModule = {
  name: 'highlight',
  group: 'inline',
  icon: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"
          fill="none" stroke="currentColor" stroke-width="2">
          <path d="M12 20h9"/><path d="M16.5 3.5l4 4L7 21l-4 1 1-4Z"/>
        </svg>`,
  label: 'Highlight',
  exec: (editor) => {
    document.execCommand('hiliteColor', false, 'yellow');
  },
};

const editor = new Editor('#editor', {
  // Merge built-ins with your custom module
  modules: [
    ...Object.values(modules),
    highlightModule,
  ],

  // Add 'highlight' to the toolbar layout
  toolbar: [
    ['bold', 'italic', 'underline', 'highlight'],
    ['h1', 'h2', 'h3', 'paragraph'],
    ['ul', 'ol', 'blockquote'],
    ['link', 'image'],
    ['undo', 'redo'],
  ],
});

A module listed in the toolbar array but absent from modules is silently skipped — no button is rendered and no error is thrown. Always make sure every command name in toolbar has a corresponding entry in modules.

To override a built-in module’s icon or behaviour, spread the original and replace only the properties you want to change:

const customBold = {
  ...modules.bold,
  icon: '<strong>B</strong>',   // swap icon only
};

TypeScript Exports

Lumen Editor ships full TypeScript declarations. The following types are exported from the lumen-editor package and can be used to type plugins, modules, and editor options in your project:

import {
  Editor,          // The editor class itself
  EditorOptions,   // Constructor options object
  EditorModule,    // Interface for toolbar module objects
  EditorPlugin,    // Type for plugin functions: (editor: Editor) => void
  EditorEvent,     // Union of all event name strings
  SanitizeConfig,  // Configuration object for the built-in HTML sanitizer
} from 'lumen-editor';

Using these types in a custom module ensures your code is checked at compile time:

import { Editor, EditorModule, EditorPlugin } from 'lumen-editor';

const highlight: EditorModule = {
  name: 'highlight',
  group: 'inline',
  icon: '★',
  label: 'Highlight',
  exec: (editor: Editor) => {
    document.execCommand('hiliteColor', false, 'yellow');
  },
};

const myPlugin: EditorPlugin = (editor: Editor) => {
  editor.on('change', () => console.log(editor.getHTML()));
};

Editor API

Plugin API

Module API: Custom Toolbar Buttons in Lumen Editor

`EditorModule` Interface

Accessing Built-in Modules

Built-in Module Names

Registering Custom Modules

TypeScript Exports

​EditorModule Interface

​Accessing Built-in Modules

​Built-in Module Names

​Registering Custom Modules

​TypeScript Exports

`EditorModule` Interface

Accessing Built-in Modules

Built-in Module Names

Registering Custom Modules

TypeScript Exports