Skip to main content

@lexical/rich-text

This package provides a starting point for Lexical users by registering listeners for a set of basic commands that cover simple text-editing behavior such as entering text, deleting characters, copy + paste, or changing the selection with arrow keys. It also provides default behavior for rich text features, such as headings, formatted, text and blockquotes.

You can use this package as a starting point, and then add additional command listeners to customize the functionality of your editor. If you don't want or need rich text functionality, you may want to consider using @lexical/plain-text instead.

Quotes: QuoteNode or QuoteContainerNode​

The package has two quote nodes. Both render as a <blockquote> with the theme's quote class.

QuoteNodeQuoteContainerNode (experimental)
JSON typequotequote-container
Holdsinline content: one block of text, lines separated by line breaksblocks: paragraphs, headings, lists, code, other quotes
Declares in $config()children: 'inline'children: 'block'
Shadow rootno (unless the shadowRoot state is set)always
Enterleaves the quote: a paragraph after itsplits the block the caret is in; the caret stays in the quote
Backspace at its startthe quote becomes a paragraphthe quote is dissolved, and its blocks stay in its place
Registered byRichTextExtensionQuoteContainerExtension

Use QuoteNode for a quote that is one passage of text, which is what the toolbar of most editors makes, and what RichTextExtension gives every editor.

Use QuoteContainerNode when a quote has structure: several paragraphs, a list, a code block, a quote inside a quote (Markdown > - item, an email reply, a <blockquote> with <p>s in it). It is a shadow root, like a table cell: the selection, the arrow keys and the block commands ($setBlocksType, $insertList) work on the blocks inside it.

QuoteNode can also hold blocks, by setting its shadowRoot state ($createQuoteNode({shadowRoot: true})), but its class still declares children: 'inline', so code that reads the declaration has to special-case it. In particular, @lexical/y stores such a quote as one line of text and its paragraphs as nodes inside that line, and a collaborator's typing can be lost when someone else splits or joins those paragraphs. QuoteContainerNode declares what it holds, so @lexical/y stores it as a container, as it stores a table cell. Prefer it for new code that needs blocks in a quote.

Using it​

QuoteContainerExtension registers the node next to QuoteNode; nothing creates one unless you ask:

import {DOMImportExtension} from '@lexical/html';
import {
$createQuoteContainerNode,
QuoteContainerExtension,
QuoteContainerRule,
} from '@lexical/rich-text';
import {
$createParagraphNode,
configExtension,
defineExtension,
} from 'lexical';

const QuotesExtension = defineExtension({
dependencies: [
QuoteContainerExtension,
// Optional: <blockquote> HTML imports as a container.
configExtension(DOMImportExtension, {rules: [QuoteContainerRule]}),
],
name: '@app/quotes',
});

// In an update:
$createQuoteContainerNode().append($createParagraphNode());

For Markdown, put QUOTE_CONTAINER in place of QUOTE in the transformers of @lexical/markdown, or add MdastQuoteContainerExtension with @lexical/mdast. Both export every block a container holds. Only @lexical/mdast imports them all (CommonMark: a block quote holds any blocks); @lexical/markdown reads a quote line by line, so it imports the paragraphs of a quote and reads any other block in it (> - item) as text. Use @lexical/mdast where Markdown may carry lists, headings or code inside a quote (an agent's Markdown, for instance).

One quote type for the whole editor​

QuoteContainerNode extends QuoteNode, so an editor can replace one with the other (node replacement). QuoteContainerReplacementExtension does it:

const editor = buildEditorFromExtensions(
defineExtension({
dependencies: [RichTextExtension, QuoteContainerReplacementExtension],
name: '@app/editor',
}),
);

which is the same as listing the replacement in an editor's nodes:

nodes: [
QuoteContainerNode,
{
replace: QuoteNode,
with: () => $createQuoteContainerNode(),
withKlass: QuoteContainerNode,
},
]

Then $createQuoteNode(), the <blockquote> import (HTML and paste), the Markdown > (QUOTE, @lexical/mdast) and JSON of type quote all build a QuoteContainerNode, and $isQuoteNode is true for it. JSON saved before loads: a quote with inline children gets them in a paragraph, and a quote with shadowRoot: true keeps its blocks.

The editor saves what it loaded as quote-container. An editor that does not register QuoteContainerNode (an older build, a server that renders the JSON) cannot read that, so ship the node everywhere the documents are read before turning the replacement on. A document shared through @lexical/y or @lexical/yjs stores the node type too: do not turn the replacement on for a shared document that already holds quote nodes without converting it first. With @lexical/y, convert by reseeding the room from its JSON (with the replacement registered, and schemaVersion bumped): quote JSON loads as containers, and the seed stores them as containers. A client with the replacement that meets a room still holding quote lines opens it read only.

A block-type toolbar that turns a quote back into paragraphs with $setBlocksType(selection, $createParagraphNode) changes the blocks the selection is in, which are inside the container, so the container stays. To take the blocks out of the quote, replace the container with its children, for example with $unwrapNode(container) from @lexical/utils; Backspace at the start of its first block does the same.

An empty container gets an empty paragraph when an edit leaves it empty. Two collaborators who each remove a different block of the last two at once each leave one locally, so no edit empties it, and the shared document ends with an empty container (a read of a collaborator's change runs no transforms). It stays editable: a caret placed in it and typing make the paragraph.