Custom plugins

This page defines shared Core behavior. Classic and Block can install it through extensions, provided its commands exist and the selected View is validated. Product controls use their own adapter contracts; see editor integration.

Suppose you want a keyboard shortcut that makes the current text bold. This adds behavior without introducing a document structure, so it uses Extension.

This chapter adds a custom shortcut to the editor from Quick start.

1. Define the shortcut

Create shortcuts.ts. Return a map of keys to handlers from addKeyboardShortcuts():

import { Extension } from '@quirekit/core'

export const writingShortcuts = Extension.create({
  name: 'writingShortcuts',
  addKeyboardShortcuts() {
    return {
      'Mod-Shift-b': () => this.editor?.commands.toggleBold() ?? false,
    }
  },
})

Mod means Command on macOS and Ctrl elsewhere. The handler invokes the existing toggleBold() command. Its return value tells the editor whether the key was handled; false lets other shortcuts try it.

name identifies this extension within the editor; it is not an npm package name. StarterKit supplies bold. The shortcut only triggers that capability and shares its document and undo history.

2. Add it to the editor

Import the extension in the file that creates Editor and add it to the existing extensions list:

import { writingShortcuts } from './shortcuts'

const editor = new Editor({
  element,
  mode: 'dom',
  extensions: [StarterKit, DomViewExtension, writingShortcuts],
  content: '<p>Select text and try the new shortcut.</p>',
})

This continues to use the Editor, StarterKit, DomViewExtension imports and element from Quick start. Install the extension once; no separate keyboard listener is needed on the host.

Live effect

Select text below and press Command+Shift+B on macOS or Ctrl+Shift+B elsewhere, then undo. The button invokes the same bold command.

Use Node or Mark for new persistent content, defining attributes, parsing and serialization. Add separate Canvas or DOCX contributions when needed; a behavior extension does not automatically support every backend.

Complete files

In the example, core/shortcuts.ts defines the shortcut and core/create.ts creates and mounts the editor. Select a file when you need its complete imports or initial content:

import { Editor } from "@quirekit/core";
import { StarterKit } from "@quirekit/starter-kit";
import { DomViewExtension } from "@quirekit/dom-view";
import { writingShortcuts } from "./shortcuts";

/**
 * Mounts a minimal editor with the Tiptap-style Core API and an explicit native DOM view.
 * @param element - Browser-owned mount target.
 * @param locale - Language for initial sample copy only.
 * @returns The caller-owned editor; destroy it when its host unmounts.
 */
export function createExampleEditor(element: HTMLElement, locale: "zh-CN" | "en"): Editor {
  return new Editor({
    element,
    mode: "dom",
    extensions: [StarterKit, DomViewExtension, writingShortcuts],
    content: { type: "doc", content: [
      { type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: locale === "en" ? "Start with your words." : "从你写下的文字开始。" }] },
      { type: "paragraph", content: [{ type: "text", text: locale === "en" ? "Select some text, make it bold, or add a new paragraph. This is a real QuireKit Core editor." : "选择一段文字，加粗，或另起一段。这里运行的是真实的 QuireKit Core 编辑器。" }] },
    ] },
  });
}

For persistent custom content and multiple backends, continue to the complete content extension. For ribbon, panels and file services, see product plugins.