Plugin API: Extending Lumen Editor with Custom Plugins

Plugins are the primary extension point for Lumen Editor. A plugin is a plain function that receives the fully initialized editor instance — nothing more, nothing less. Because every editor method and event is accessible from inside a plugin, you can build anything from a word-count sidebar to a collaborative cursor indicator without touching editor internals.

Plugin Signature

A plugin conforms to the EditorPlugin type:

type EditorPlugin = (editor: Editor) => void;

The function receives the Editor instance and should perform all its setup work synchronously — subscribing to events, appending UI elements, patching methods, etc. The return value is ignored.

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

const myPlugin: EditorPlugin = (editor) => {
  // Set up your plugin here
};

What Plugins Can Do

Because plugins receive the full editor instance, they can:

Subscribe to events using editor.on() and clean up with editor.off() to react to content changes, errors, view switches, and more.
Read and write content by calling editor.getHTML(), editor.getText(), and editor.setHTML().
Append UI to the editor root by accessing editor.root — the underlying contenteditable element — and inserting sibling or wrapper nodes.
Call any public method including editor.focus(), editor.blur(), editor.setTheme(), and editor.use() to compose behaviour across plugins.
Add side effects such as starting a MutationObserver, registering keyboard shortcuts via document.addEventListener, or initializing third-party libraries that operate on the editor’s DOM.

Installing a Plugin

Via the constructor

Pass an array of plugin functions to the plugins option. Plugins run synchronously in array order immediately after the editor mounts:

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

function analyticsPlugin(editor) {
  editor.on('change', () => {
    analytics.track('editor_change');
  });
}

function autoLinkPlugin(editor) {
  editor.on('change', (html) => {
    // auto-link detection logic …
  });
}

const editor = new Editor('#editor', {
  plugins: [analyticsPlugin, autoLinkPlugin],
});

Via `editor.use()`

Install a plugin at any point after initialization using editor.use(). This is useful for lazy-loading plugins or for conditionally applying them based on runtime state:

import { wordCountPlugin } from './plugins/wordCount';

// Install immediately
editor.use(wordCountPlugin);

// Or install after an async check
const flags = await fetchFeatureFlags();
if (flags.enableWordCount) {
  editor.use(wordCountPlugin);
}

Plugins run synchronously — whether registered in the plugins constructor option or installed via editor.use(). All setup code inside a plugin executes before the next JavaScript statement after the constructor or use() call returns.

Full Example: Word Count Plugin

The following plugin appends a live word count badge below the editor and keeps it updated on every content change:

function wordCountPlugin(editor) {
  // Create the badge element
  const badge = document.createElement('div');
  badge.className = 'wc';

  // Append it inside the editor root
  editor.root.appendChild(badge);

  // Keep it in sync with content changes
  editor.on('change', () => {
    badge.textContent =
      editor.getText().trim().split(/\s+/).filter(Boolean).length + ' words';
  });
}

// Install via options
const editor = new Editor('#editor', {
  plugins: [wordCountPlugin],
});

// — or install after the fact —
editor.use(wordCountPlugin);

Accessing the Editor Root

editor.root is the contenteditable HTMLElement that hosts the document. You can use it as an anchor for additional DOM nodes, event delegation, or position-aware UI like floating toolbars:

function floatingMenuPlugin(editor) {
  const menu = document.createElement('div');
  menu.className = 'floating-menu';
  menu.hidden = true;

  // Position the menu relative to the editor root
  document.body.appendChild(menu);

  editor.on('selectionchange', () => {
    const sel = window.getSelection();
    if (!sel || sel.isCollapsed) {
      menu.hidden = true;
      return;
    }

    const range = sel.getRangeAt(0);
    const rect = range.getBoundingClientRect();

    menu.style.setProperty('--menu-top', `${rect.top + window.scrollY - 40}px`);
    menu.style.setProperty('--menu-left', `${rect.left}px`);
    menu.hidden = false;
  });
}

If your plugin appends DOM nodes, consider removing them inside a cleanup handler. While Lumen Editor does not provide a formal plugin teardown hook, you can subscribe to a signal of your own (e.g. a custom event or a shared AbortSignal) to remove nodes and unsubscribe event listeners before calling editor.destroy().

​Plugin Signature

​What Plugins Can Do

​Installing a Plugin

​Via the constructor

​Via editor.use()

​Full Example: Word Count Plugin

​Accessing the Editor Root

Plugin Signature

What Plugins Can Do

Installing a Plugin

Via the constructor

Via `editor.use()`

Full Example: Word Count Plugin

Accessing the Editor Root