Rich Text Editor
The editor is the most important property of the rich text field.
As a key part of Payload, we are proud to offer you the best editing experience you can imagine. With healthy defaults out of the box, but also with the flexibility to customize every detail: from the “/” menu and toolbars (whether inline or fixed) to inserting any component or subfield you can imagine.
To use the rich text editor, first you need to install it:
Once you have it installed, you can pass it to your top-level Payload Config as follows:
You can also override Lexical settings on a field-by-field basis as follows:
Extending the lexical editor with Features
Lexical has been designed with extensibility in mind. Whether you're aiming to introduce new functionalities or tweak the existing ones, Lexical makes it seamless for you to bring those changes to life.
Features: The Building Blocks
At the heart of Lexical's customization potential are "features". While Lexical ships with a set of default features we believe are essential for most use cases, the true power lies in your ability to redefine, expand, or prune these as needed.
If you remove all the default features, you're left with a blank editor. You can then add in only the features you need, or you can build your own custom features from scratch.
Integrating New Features
To weave in your custom features, utilize the features prop when initializing the Lexical Editor. Here's a basic example of how this is done:
features can be both an array of features, or a function returning an array of features. The function provides the following props:
Prop | Description |
|---|---|
| This opinionated array contains all "recommended" default features. You can see which features are included in the default features in the table below. |
| This array contains all features that are enabled in the root richText editor (the one defined in the payload.config.ts). If this field is the root richText editor, or if the root richText editor is not a lexical editor, this array will be empty. |
Features overview
Here's an overview of all the included features:
Feature Name | Included by default | Description |
|---|---|---|
| Yes | Handles the bold text format |
| Yes | Handles the italic text format |
| Yes | Handles the underline text format |
| Yes | Handles the strikethrough text format |
| Yes | Handles the subscript text format |
| Yes | Handles the superscript text format |
| Yes | Handles the inline-code text format |
| Yes | Handles paragraphs. Since they are already a key feature of lexical itself, this Feature mainly handles the Slash and Add-Block menu entries for paragraphs |
| Yes | Adds Heading Nodes (by default, H1 - H6, but that can be customized) |
| Yes | Allows you to align text left, centered and right |
| Yes | Allows you to indent text with the tab key |
| Yes | Adds unordered lists (ul) |
| Yes | Adds ordered lists (ol) |
| Yes | Adds checklists |
| Yes | Allows you to create internal and external links |
| Yes | Allows you to create block-level (not inline) relationships to other documents |
| Yes | Allows you to create block-level quotes |
| Yes | Allows you to create block-level upload nodes - this supports all kinds of uploads, not just images |
| Yes | Horizontal rules / separators. Basically displays an |
| Yes | The inline toolbar is the floating toolbar which appears when you select text. This toolbar only contains actions relevant for selected text |
| No | This classic toolbar is pinned to the top and always visible. Both inline and fixed toolbars can be enabled at the same time. |
| No | Allows you to use Payload's Blocks Field directly inside your editor. In the feature props, you can specify the allowed blocks - just like in the Blocks field. |
| No | Adds a debug box under the editor, which allows you to see the current editor state live, the dom, as well as time travel. Very useful for debugging |
| No | Adds support for tables. This feature may be removed or receive breaking changes in the future - even within a stable lexical release, without needing a major release. |
| No | Allows you to store key-value attributes within TextNodes and assign them inline styles. |
Notice how even the toolbars are features? That's how extensible our lexical editor is - you could theoretically create your own toolbar if you wanted to!
Creating your own, custom Feature
You can find more information about creating your own feature in our building custom feature docs.
TypeScript
Every single piece of saved data is 100% fully typed within lexical. It provides a type for every single node, which can be imported from @payloadcms/richtext-lexical - each type is prefixed with Serialized, e.g., SerializedUploadNode.
To fully type the entire editor JSON, you can use our TypedEditorState helper type, which accepts a union of all possible node types as a generic. We don't provide a type that already contains all possible node types because they depend on which features you have enabled in your editor. Here is an example:
Alternatively, you can use the DefaultTypedEditorState type, which includes all types for all nodes included in the defaultFeatures:
Just like TypedEditorState, the DefaultTypedEditorState also accepts an optional node type union as a generic. Here, this would add the specified node types to the default ones. Example:
This is a type-safe representation of the editor state. If you look at the auto suggestions of a node's type property, you will see all the possible node types you can use.
Make sure to only use types exported from @payloadcms/richtext-lexical, not from the lexical core packages. We only have control over the types we export and can make sure they're correct, even though the lexical core may export types with identical names.
Automatic type generation
Lexical does not generate accurate type definitions for your richText fields for you yet - this will be improved in the future. Currently, it only outputs the rough shape of the editor JSON, which you can enhance using type assertions.
Admin customization
The Rich Text Field editor configuration has an admin property with the following options:
Property | Description |
|---|---|
| Set this property to define a placeholder string for the field. |
| Set this property to |
| Set this property to |
Disable the gutter
You can disable the gutter (the vertical line padding between the editor and the left edge of the screen) by setting the hideGutter prop to true:
Customize the placeholder
You can customize the placeholder (the text that appears in the editor when it's empty) by setting the placeholder prop:
Detecting empty editor state
When you first type into a rich text field and subsequently delete everything through the admin panel, its value changes from null to a JSON object containing an empty paragraph.
If needed, you can reset the field value to null programmatically - for example, by using a custom hook to detect when the editor is empty.
This also applies to fields like text and textArea, which could be stored as either null or an empty value in the database. Since the empty value for richText is a JSON object, checking for emptiness is a bit more involved - so Payload provides a utility for it: