Tools & plugins
Pick the blocks and formatting the editor offers, arrange its toolbar, and add your own blocks with plugins.
Choosing tools#
Pass tools to list the tools you want. A tool that's off is gone everywhere: the / and + menus, Markdown shortcuts, keyboard shortcuts, the formatting toolbar, and the mobile toolbar. Pasted content it would have produced becomes plain paragraphs, and existing content falls back the same way when it loads. Paragraphs are always on. Without tools, every built-in tool and every plugin is on.
<BlockEditor tools={["heading", "bulletList", "image", "bold", "link"]} />The object form takes options. Keys set to an options object or true are on:
<BlockEditor
tools={{
heading: { levels: [1, 2] },
image: true,
bold: true,
italic: true,
}}
/>import { BlockEditor } from "genesis-editor";
export default function ToolsBasicExample() {
return (
<BlockEditor
tools={{ heading: { levels: [1, 2] }, image: true }}
initialContent={[
{ type: "heading", props: { level: 2 }, content: "Headings and images only" },
{
type: "paragraph",
content: "Type / to see the menu: Heading 1, Heading 2, Image, and Paragraph. # and ## work, - and > don't.",
},
]}
/>
);
}
To start from everything and remove a few, filter the exported list:
import { BUILT_IN_TOOLS } from "genesis-editor";
<BlockEditor tools={BUILT_IN_TOOLS.filter((tool) => tool !== "table")} />Built-in tools
| Tool | Kind | What it adds |
|---|---|---|
| heading | Block | Headings 1–6 (menus show 1–3). Options: { levels }. Shortcuts # to ######. |
| bulletList | Block | Bullet lists. Shortcut - or *. |
| numberedList | Block | Numbered lists. Shortcut 1. |
| checkList | Block | To-do lists. Shortcut [] or [x]. |
| toggleList | Block | Collapsible toggle lists. |
| quote | Block | Block quotes. Shortcut >. |
| codeBlock | Block | Code blocks with a language picker and syntax highlighting. Shortcut ```. |
| divider | Block | Horizontal dividers. Shortcut ---. |
| table | Block | Tables. |
| columns | Block | Two- or three-column layouts. Slash /Columns (2) or /3 columns; drag to resize. |
| image | Block | Images: by URL, upload, paste, or drop. |
| video | Block | Video files. |
| audio | Block | Audio files. |
| file | Block | Any file. Also catches pasted files no other block accepts. |
| embed | Block | |
| linkPreview | Block | |
| bold | Inline | Bold. Mod+B. |
| italic | Inline | Italic. Mod+I. |
| underline | Inline | Underline. Mod+U. |
| strike | Inline | Strikethrough. Mod+Shift+S. |
| code | Inline | Inline code. Mod+E. |
| link | Inline | Links: toolbar button, Mod+K, pasted links. |
| colors | Inline | Text and background colors: palette, brand swatches and any hex. |
| fontSize | Inline |
Toolbar#
toolbar picks the formatting toolbar's items and their order. Items for tools that are off are skipped. The default order is blockType, tableMerge, columns, file, imageLink, inlineImage, bold, italic, underline, strike, code, alignLeft, alignCenter, alignRight, linkPreview, then any plugin items.
import { BlockEditor } from "genesis-editor";
export default function ToolsMinimalToolbarExample() {
return (
<BlockEditor
tools={["bulletList", "bold", "italic", "link"]}
toolbar={["bold", "italic", "link"]}
initialContent={[
{ type: "paragraph", content: "Select some text: the toolbar has Bold, Italic, and Link." },
{ type: "bulletListItem", content: "Underline, colors, and headings are off." },
]}
/>
);
}
Set placement: "fixed" to pin the toolbar above the editor instead of showing it over the selection, or pass toolbar={false} to turn it off.
import { BlockEditor } from "genesis-editor";
export default function ToolsFixedToolbarExample() {
return (
<BlockEditor
toolbar={{
placement: "fixed",
items: ["blockType", "bold", "italic", "underline", "code", "link"],
}}
initialContent={[{ type: "paragraph", content: "The toolbar stays above the editor." }]}
/>
);
}
Plugins#
A plugin bundles blocks, menu items, toolbar items, and shortcuts under one name. Declare it with definePlugin and pass it in plugins. Its blocks join the same menus as the built-ins, and its name works in tools like any built-in tool. The built-in tools are plugins too, so a plugin named quote replaces the built-in quote.
import { definePlugin } from "genesis-editor";
export const myPlugin = definePlugin({
name: "my-plugin", // also its tool name
blocks: { … }, // block specs, e.g. createReactBlockSpec(...)()
slashItems: [ … ], // entries for the / and + menus
toolbarItems: { … }, // formatting toolbar components, by toolbar name
markdownShortcuts: [ … ], // { find: /^!>\s$/, block: { type: "callout" } }
keyboardShortcuts: { … }, // { "Mod-Shift-l": (editor) => true }
});This callout plugin adds a block with a tone you can click to change, a slash menu item, a !> Markdown shortcut, and a toolbar button. It ships with these docs, not with the package.
import { BlockEditor } from "genesis-editor";
import { calloutPlugin } from "./callout-plugin";
export default function PluginCalloutExample() {
return (
<BlockEditor
plugins={[calloutPlugin]}
initialContent={[
{ type: "callout", content: "Plugins add blocks to every menu. Click the icon to change the tone." },
{ type: "paragraph", content: 'Type /callout, or "!> " at the start of a line.' },
]}
/>
);
}
import { createReactBlockSpec, definePlugin, ToolbarButton, type AnyEditor } from "genesis-editor";
import { LightbulbIcon } from "lucide-react";
import "./callout-plugin.css";
const tones = { info: "💡", warning: "⚠️", success: "✅" } as const;
type Tone = keyof typeof tones;
const nextTone: Record<Tone, Tone> = { info: "warning", warning: "success", success: "info" };
const createCallout = createReactBlockSpec(
{
type: "callout",
propSchema: { tone: { default: "info", values: ["info", "warning", "success"] } },
content: "inline",
},
{
render: ({ block, editor, contentRef }) => {
const tone = block.props.tone as Tone;
return (
<div className="callout" data-tone={tone}>
<button
type="button"
className="callout-icon"
contentEditable={false}
aria-label={`Callout tone: ${tone}. Click to change.`}
onClick={() => editor.updateBlock(block, { props: { tone: nextTone[tone] } })}
>
{tones[tone]}
</button>
<div className="callout-content" ref={contentRef} />
</div>
);
},
},
);
const currentBlockType = (editor: AnyEditor) => editor.getTextCursorPosition().block.type;
function CalloutToolbarButton() {
return (
<ToolbarButton
label="Callout"
icon={<LightbulbIcon size={16} />}
isSelected={(editor) => currentBlockType(editor) === "callout"}
onClick={(editor) => {
const block = editor.getTextCursorPosition().block;
editor.updateBlock(block, { type: currentBlockType(editor) === "callout" ? "paragraph" : "callout" });
}}
/>
);
}
export const calloutPlugin = definePlugin({
name: "callout",
blocks: { callout: createCallout() },
slashItems: [
{
key: "callout",
title: "Callout",
subtext: "Highlight a tip or a warning",
aliases: ["note", "tip", "warning"],
group: "Basic blocks",
icon: <LightbulbIcon size={18} />,
block: { type: "callout" },
},
],
// Type "!> " at the start of a line.
markdownShortcuts: [{ find: /^!>\s$/, block: { type: "callout" } }],
toolbarItems: { callout: CalloutToolbarButton },
});
.callout {
--callout-background: oklch(0.96 0.03 250);
display: flex;
flex-grow: 1;
gap: 0.625rem;
padding: 0.625rem 0.875rem;
border-radius: 0.5rem;
background: var(--callout-background);
}
.callout[data-tone="warning"] {
--callout-background: oklch(0.96 0.05 85);
}
.callout[data-tone="success"] {
--callout-background: oklch(0.96 0.04 150);
}
[data-color-scheme="dark"] .callout {
--callout-background: oklch(0.3 0.04 250);
}
[data-color-scheme="dark"] .callout[data-tone="warning"] {
--callout-background: oklch(0.32 0.05 85);
}
[data-color-scheme="dark"] .callout[data-tone="success"] {
--callout-background: oklch(0.3 0.04 150);
}
.callout-icon {
flex-shrink: 0;
height: 1.5em;
cursor: pointer;
user-select: none;
}
.callout-content {
flex-grow: 1;
}
// With a tools list, plugins are active only when listed.
<BlockEditor tools={["heading", "callout"]} plugins={[calloutPlugin]} />tools and the plugin names are read when the editor is created. When they change, the editor is rebuilt with the current document, which keeps its content but loses undo history. Every field of a plugin is listed in the API reference.