Footnote turns GFM footnote markup ([^1] references and [^1]: text definitions) into dedicated Plate nodes you can insert, repair, and jump between. The reference is an inline void <sup>; the definition is a block at the end of the document. Paired with MarkdownPlugin and remark-gfm, references and definitions round-trip as real footnote markdown instead of fallback text.
[^ inline combobox for insertion from the default UI kit.The fastest way to add footnote-aware markdown is with the MarkdownKit, which includes MarkdownPlugin, the footnote plugins wired for the default markdown profile, and works with Plate UI.
import { MarkdownPlugin, remarkMdx, remarkMention } from '@platejs/markdown';
import { PLUGINS } from 'platejs';
import remarkEmoji from 'remark-emoji';
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
export const MarkdownKit = [
MarkdownPlugin.configure(({ editor }) => {
const comment = editor.plugin(PLUGINS.comment);
const suggestion = editor.plugin(PLUGINS.suggestion);
const plainMarks: string[] = [];
if (suggestion.installed) {
plainMarks.push(suggestion.schema.key);
}
if (comment.installed) {
plainMarks.push(comment.schema.key);
}
return {
initialState: {
plainMarks,
remarkPlugins: [
remarkMath,
remarkGfm,
remarkEmoji,
remarkMdx,
remarkMention,
],
},
};
}),
];import { MarkdownPlugin, remarkMdx, remarkMention } from '@platejs/markdown';
import { PLUGINS } from 'platejs';
import remarkEmoji from 'remark-emoji';
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
export const MarkdownKit = [
MarkdownPlugin.configure(({ editor }) => {
const comment = editor.plugin(PLUGINS.comment);
const suggestion = editor.plugin(PLUGINS.suggestion);
const plainMarks: string[] =
import { createPlateEditor } from 'platejs/react';
import { MarkdownKit } from '@/components/editor/markdown';
const editor = createPlateEditor({
plugins: [
// ...otherPlugins,
...MarkdownKit,
],
});import { createPlateEditor } from 'platejs/react';
import { MarkdownKit } from '@/components/editor/markdown';
const editor = createPlateEditor
Add the inline reference and block definition. FootnotePlugin installs its combobox input as a required dependency; pair the footnote plugins with MarkdownPlugin and remark-gfm so [^1] round-trips correctly.
import {
FootnoteDefinitionPlugin,
FootnotePlugin,
} from '@platejs/footnote/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { createPlateEditor } from 'platejs/react';
import remarkGfm from 'remark-gfm';
const editor = createPlateEditor({
plugins: [
// ...otherPlugins,
FootnotePlugin,
FootnoteDefinitionPlugin,
MarkdownPlugin.configure({
initialState: {
remarkPlugins: [remarkGfm],
},
}),
],
});FootnoteInputPlugin is a required dependency of FootnotePlugin. Add a complete input descriptor to the same array only when you need to replace its default component or configuration.
Call tx.footnote.insert at the current selection. It inserts the reference, creates a matching definition at the end of the document, and moves the caret into the definition body so the reader can start writing:
editor.update((tx) => tx.footnote.insert());editor.update((tx) => tx.footnote.insert());When the selection is expanded, the expanded fragment seeds the definition body so you can select text and "footnote-ify" it in one shot.
Pass focusDefinition: false when the reference should stay inline (for example, inside a larger template):
editor.update((tx) => tx.footnote.insert({ focusDefinition: false }));editor.update((tx) => tx.footnote.insert({ focusDefinition: false }));Pass ref to reuse an existing ref; the transform skips creating a duplicate definition when one already exists.
When a reference points at an ref with no definition (e.g. pasted from elsewhere), use tx.footnote.createDefinition to create just the definition — without inserting another reference:
editor.update((tx) => tx.footnote.createDefinition({ ref: '3' }));editor.update((tx) => tx.footnote.createDefinition({ ref: '3' }));Pass focus: false when you want to leave the caret where it was:
editor.update((tx) =>
tx.footnote.createDefinition({ focus: false, ref: '3' })
);editor.update((tx) =>
tx.footnote.createDefinition({ focus: false, ref: '3' })
);tx.footnote.focusDefinition and tx.footnote.focusReference jump the selection, scroll the target into view, and flash it through Navigation Feedback. No extra wiring needed:
editor.update((tx) => tx.footnote.focusDefinition({ ref: '3' }));
editor.update((tx) => tx.footnote.focusReference({ ref: '3' }));editor.update((tx) => tx.footnote.focusDefinition({ ref: '3' }));
editor.update((tx) => tx.footnote.focusReference({ ref: '3' }));When a single definition is pointed at by multiple references, pass index to pick which one to land on:
editor.update((tx) =>
tx.footnote.focusReference({ ref: '3', index: 1 })
);editor.update((tx) =>
tx.footnote.focusReference({ ref: '3', index: 1 })
);Both transaction commands return false when the ref doesn't resolve, so you can branch on stale links without throwing.
Two definitions with the same ref is a resolvable edit state, not an error. The first definition in document order stays canonical; later ones are flagged as duplicates. Renumber a later duplicate with:
let nextRefentifier: string | undefined;
editor.update((tx) => {
nextRefentifier = tx.footnote.normalizeDuplicateDefinition({
path: duplicatePath,
});
});let nextRefentifier: string | undefined;
editor.update((tx) => {
nextRefentifier = tx.footnote.normalizeDuplicateDefinition({
The transform returns the newly assigned ref string on success, or false when the path isn't a duplicate definition or the requested ref is already taken. Pass ref to target a specific free ref instead of the next available one.
Swap in your own React components with component:
import {
FootnoteDefinitionPlugin,
FootnotePlugin,
} from '@platejs/footnote/react';
import { createPlateEditor } from 'platejs/react';
const editor = createPlateEditor({
plugins: [
FootnotePlugin.configure({ component: MyFootnoteReference }),
FootnoteDefinitionPlugin.configure({ component: MyFootnoteDefinition }),
],
});import {
FootnoteDefinitionPlugin,
The package owns node semantics, ref allocation, and navigation helpers. App-level surfaces — hover previews, the [^ combobox, slash-command entries, toolbar buttons — are built on top of the transforms and API methods below.
Inline void node rendered as <sup>. Owns the [^ combobox trigger, ref registry, navigation transforms, and query API. Requires FootnoteInputPlugin.
Character that opens the footnote combobox.
'^'Only trigger when the previous character matches. The default requires [ so bare ^ in prose doesn't open the combobox.
/^\[$/Factory for the node inserted when the combobox opens. Defaults to a footnoteInput element.
Extra predicate gating the combobox. Return false to suppress triggering at the current selection.
Block node for footnote definitions. Lives at the bottom of the document and carries the ref + body content.
Inline void used as the live combobox input while the reader is typing [^…. Installed as a required dependency of FootnotePlugin; add it directly only to replace its default configuration or component.
All read methods hang off editor.read.footnote and evaluate the active
snapshot directly.
Get the canonical (first-in-document-order) definition entry for an ref.
Get every definition entry that shares an ref, in document order. When duplicates exist, the first entry is canonical; later entries are duplicates.
Get the plain-text content of the canonical definition. Ideal for hover previews — reads straight from live definition nodes, no copied state.
Get every reference entry that points at an ref, in document order.
List every ref that has at least one definition, in document order.
Compute the next free numeric ref. Used by tx.footnote.insert when the caller doesn't supply one.
Check whether an ref has at least one definition.
Get every non-canonical definition entry for an ref — that is, every definition after the first in document order.
List every ref that has more than one definition.
Check whether an ref has more than one definition.
Check whether a given definition path is a later duplicate (not the canonical one).
Insert a footnote reference at the current selection, create a matching definition if one doesn't already exist, and focus the definition body.
When the selection is expanded, the expanded fragment seeds the new definition body so you can convert selected prose into a footnote in one call.
Create the missing definition for an existing ref without inserting another reference. Returns the path of the definition — the newly created one, or the existing one when the ref already resolves.
Jump the selection into the canonical definition body, scroll it into view, and flash it through Navigation Feedback.
Jump the selection to the matching reference, scroll it into view, and flash it through Navigation Feedback.
Renumber a later duplicate definition so the canonical definition stays intact. Pass the path of the duplicate; optionally pass a specific ref to target, otherwise the transform picks editor.read.footnote.nextRef().
import {
FootnoteDefinitionPlugin,
FootnotePlugin,
} from '@platejs/footnote/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { createPlateEditor } from 'platejs/react';
import remarkGfm from 'remark-gfm';
const editor = createPlateEditor({
plugins: [
// ...otherPlugins,
FootnotePlugin,
FootnoteDefinitionPlugin,
MarkdownPlugin.configure({
initialState: {
remarkPlugins: [remarkGfm],
},
}),
],
});