You’ve added a richText field to a Payload collection, and now you need to know what the editor can do, how to change it and how to show what it saves on your site. The editor decides what your writers can format, and what it saves decides how much work your front end has to do.
As of 13 November 2026, Payload’s editor is @payloadcms/richtext-lexical 3.93.0, built on Meta’s Lexical. It’s a WYSIWYG editor in the admin panel that saves JSON, with 20 features switched on by default. This guide takes it from the config to your front end, and covers what Payload 4 changes.
We build client projects on Payload from our own project template, which uses this editor for every rich text field.
- How the rich text editor works in Payload
- What the editor saves: Lexical JSON, not HTML
- Which features are on by default
- How to add, remove and configure features
- Blocks and inline blocks inside the editor
- Tables in the editor
- Text colour and styles with TextStateFeature
- Markdown in the editor: shortcuts and conversion
- How to render rich text on your front end
- Converting rich text to HTML or plain text
- When to build a custom feature
- Moving from Slate to Lexical
- What changes for rich text in Payload 4
- How we set up rich text on our builds
- Frequently asked questions
- What to do next
How the rich text editor works in Payload
Payload’s rich text editor is Lexical, installed as the @payloadcms/richtext-lexical package and passed to your config as lexicalEditor(). You set it once at the top of the config as editor, and every richText field uses that editor unless the field sets its own.
For example, take a cookery school in Dubai that publishes a recipe journal from Payload. Its posts collection needs one rich text body, and the config starts like this:
import { buildConfig } from 'payload'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
export default buildConfig({
editor: lexicalEditor(),
collections: [
{
slug: 'posts',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'content', type: 'richText' },
],
},
],
// db, secret and the rest of your config
})The richText field itself is one of Payload’s 22 field types.
"Editor" in Payload can also mean the admin’s edit view, the screen that holds all of a document’s fields, which you change with custom components.
What the editor saves: Lexical JSON, not HTML
A rich text field saves the editor’s state as JSON, a tree of nodes with a root, block nodes such as paragraphs and headings, and text nodes inside them. Formatting is a number on the text node, links and uploads are nodes of their own, and blocks keep their fields as data.
For example, the sentence "Preheat the oven" with the first word in bold is saved like this (trimmed):
{
"root": {
"type": "root",
"children": [
{
"type": "paragraph",
"children": [
{ "type": "text", "text": "Preheat", "format": 1 },
{ "type": "text", "text": " the oven", "format": 0 }
]
}
]
}
}Because it’s JSON, the same body can become React on a website, HTML in an email or plain text for search, and an FAQ block arrives as its questions and answers, with no markup to parse. The package exports a type for every node, and DefaultTypedEditorState types the whole state for the default features.
Keep in mind that an editor someone typed in and then cleared saves an empty paragraph, not null. The hasText helper from @payloadcms/richtext-lexical/shared tells you whether there’s any text. If your content is multilingual, a localised rich text field stores one of these JSON trees per language, as our localisation guide explains.
Which features are on by default
In 3.93.0, lexicalEditor() with no options turns on 20 features, and five more are off until you add them. The Markdown column shows what a writer can type to get the same result.
| Feature | On by default | What it adds | Markdown shortcut |
|---|---|---|---|
BoldFeature, ItalicFeature, UnderlineFeature, StrikethroughFeature, SubscriptFeature, SuperscriptFeature, InlineCodeFeature | yes | text formats | **bold**, *italic*, ~~strike~~, `code` |
ParagraphFeature | yes | paragraph entries in the menus | none |
HeadingFeature | yes | H1 to H6, or the sizes you list | # to ###### |
AlignFeature | yes | left, centre, right, justify | none |
IndentFeature | yes | indenting with Tab | none |
UnorderedListFeature | yes | bulleted lists | -, * or + |
OrderedListFeature | yes | numbered lists | 1. |
ChecklistFeature | yes | checklists | - [ ] and - [x] |
LinkFeature | yes | external links and links to documents | [text](url) |
RelationshipFeature | yes | a block that points at another document | none |
BlockquoteFeature | yes | quotes | > |
UploadFeature | yes | an image or file from an upload collection | none |
HorizontalRuleFeature | yes | a divider | --- |
InlineToolbarFeature | yes | a toolbar on selected text | none |
FixedToolbarFeature | no | a toolbar pinned above the editor | none |
BlocksFeature | no | your own blocks and inline blocks | none |
EXPERIMENTAL_TableFeature | no | tables | none |
TextStateFeature | no | colours and styles on text | none |
TreeViewFeature | no | a debug panel showing the editor state | none |
The defaults suit a general-purpose article body. Every feature you leave on is one more thing writers can use and your front end has to render.
How to add, remove and configure features
You change the features through the features option of lexicalEditor(). Pass an array and the editor gets exactly those features. Pass a function and you get two lists to build from, defaultFeatures (the 20 above) and rootFeatures (whatever the config-level editor has).
Payload’s own website template uses both. Its config-level editor is cut down to five features, and each rich text field adds what it needs on top with rootFeatures. The cookery school follows the same pattern, so every rich text field in its project gets paragraphs, bold, italic, links and the inline toolbar, and only the journal’s body gets headings, lists, photos and a fixed toolbar:
import {
BoldFeature,
FixedToolbarFeature,
HeadingFeature,
InlineToolbarFeature,
ItalicFeature,
LinkFeature,
OrderedListFeature,
ParagraphFeature,
UnorderedListFeature,
UploadFeature,
lexicalEditor,
} from '@payloadcms/richtext-lexical'
// In buildConfig: the editor every rich text field starts from
editor: lexicalEditor({
features: [
ParagraphFeature(),
BoldFeature(),
ItalicFeature(),
LinkFeature({ enabledCollections: ['posts', 'courses'] }),
InlineToolbarFeature(),
],
}),
// In the posts collection: the body adds its own features
{
name: 'content',
type: 'richText',
editor: lexicalEditor({
features: ({ rootFeatures }) => [
...rootFeatures,
HeadingFeature({ enabledHeadingSizes: ['h2', 'h3'] }),
UnorderedListFeature(),
OrderedListFeature(),
UploadFeature({
collections: {
media: { fields: [{ name: 'caption', type: 'text' }] },
},
}),
FixedToolbarFeature(),
],
}),
}Each feature takes its options when you call it. HeadingFeature limits the heading sizes, so writers can’t add a second H1 under the page title. lexicalEditor() also takes an admin object for the editor’s look, such as a placeholder or hideGutter: true.
Toolbars: inline, fixed or both
The inline toolbar is on by default and appears when a writer selects text. FixedToolbarFeature pins one above the editor with every action in it, for writers who don’t use the slash menu, and the two can run together.
Links, uploads and relationships inside rich text
A link is either a URL or an internal link to a document. enabledCollections sets which collections writers can link to, and fields adds your own options to the link drawer, such as a rel select. The cookery school limits internal links to posts and courses, so a recipe can point at the course that teaches it.
An upload node shows a document from an upload collection, and the collections option adds fields to it per collection, like the caption above. A relationship node embeds a reference to another document, and maxDepth on both features caps how far each one is populated when you read the content.
Blocks and inline blocks inside the editor
BlocksFeature puts Payload blocks inside the rich text, so a writer can drop a structured piece into the middle of an article. A block takes a whole line, and an inline block sits inside a sentence. Both carry real fields with validation and hooks, and their data is saved inside the rich text JSON.
A block in the editor uses the same config as a block in a blocks field, so you can define it once and offer it in both places. Columns, a media gallery, a data table, an FAQ or a call to action can appear in a page’s layout and in the middle of an article from one definition, with its fields and layout intact.
For example, the cookery school defines a book-a-class call to action and an FAQ once. Its landing pages use both in their layout, and the journal’s writers drop them into a recipe post, next to an inline block for oven temperatures:
import type { Block } from 'payload'
import { BlocksFeature } from '@payloadcms/richtext-lexical'
export const BookClass: Block = {
slug: 'bookClass',
interfaceName: 'BookClassBlock',
fields: [
{ name: 'course', type: 'relationship', relationTo: 'courses', required: true },
{ name: 'label', type: 'text', defaultValue: 'Book a class' },
],
}
export const Faq: Block = {
slug: 'faq',
interfaceName: 'FaqBlock',
fields: [
{
name: 'items',
type: 'array',
fields: [
{ name: 'question', type: 'text', required: true },
{ name: 'answer', type: 'textarea', required: true },
],
},
],
}
const OvenTemp: Block = {
slug: 'ovenTemp',
interfaceName: 'OvenTempBlock',
fields: [{ name: 'celsius', type: 'number', required: true }],
}
// The pages collection's layout field
{ name: 'layout', type: 'blocks', blocks: [BookClass, Faq] }
// The posts collection's content field, among its features
BlocksFeature({ blocks: [BookClass, Faq], inlineBlocks: [OvenTemp] })Because the FAQ’s questions are data, the code that renders the block can also output the page’s FAQPage structured data from the same items. Payload also ships a ready-made code block, CodeBlock, with syntax highlighting and a language picker, which you pass into blocks like your own.
Tables in the editor
Tables come from EXPERIMENTAL_TableFeature in 3.93.0. It’s off by default, so you add it to a field’s features like any other, and writers then insert a table from the toolbar or the slash menu. Payload’s features docs warn that it may change, or be removed, even within a minor release, so pin your Payload version and test tables when you upgrade.
For example, the journal adds EXPERIMENTAL_TableFeature() to the content field for a table of oven temperatures and cup-to-gram conversions. In 3.93.0 both of Payload’s converters render tables, through TableJSXConverter and TableHTMLConverter, so the table shows on the site and in the email without extra work.
If your front end or the API needs to filter, sort or reuse the rows, store them in an array field with one field per column instead. Payload 4.0.0-beta.8 renames the feature TableFeature.
Text colour and styles with TextStateFeature
TextStateFeature lets writers apply colours and styles to text, from a set you define. You give it a state object. Each key is an attribute such as color, each value is an option with a label and the CSS it applies, and the package exports defaultColors as a starting set.
For example, the cookery school wants allergens such as nuts and sesame to stand out in red:
import { TextStateFeature } from '@payloadcms/richtext-lexical'
TextStateFeature({
state: {
color: {
allergen: { label: 'Allergen', css: { color: '#b91c1c' } },
},
},
})The editor shows the colour straight away, but your front end won’t. The choice is saved on the text node under a $ key, so Payload’s rendering guide for this feature has you override the text converter to read that key and apply the CSS. Keep the state object in its own file so the editor config and the front end import the same values.
Markdown in the editor: shortcuts and conversion
Payload doesn’t have a Markdown field type, but its rich text editor handles Markdown as shortcuts while writing and as a format you convert to and from.
Each feature brings its own shortcuts, so with headings and lists on, typing ## starts a heading and - starts a list, while a feature that’s off ignores its shortcut. For conversion, convertMarkdownToLexical and convertLexicalToMarkdown turn Markdown into the editor’s JSON and back. Both need the editor config, so they only produce the nodes your features allow.
For example, the cookery school imports its old Markdown posts once, through the Local API:
import { getPayload } from 'payload'
import {
convertMarkdownToLexical,
editorConfigFactory,
} from '@payloadcms/richtext-lexical'
import config from '@payload-config'
const payload = await getPayload({ config })
const editorConfig = await editorConfigFactory.default({ config: payload.config })
// title and markdown come from each old post's file
const content = convertMarkdownToLexical({ editorConfig, markdown })
await payload.create({
collection: 'posts',
data: { title, content },
})Markdown image links don’t become uploads, because Payload can’t look up a media document from a URL. Upload the images first and use the upload placeholder the converter understands, as the Markdown docs describe. Blocks can be written to and read from MDX through a jsx option on each block. Importing HTML from another CMS is a different route, covered in our guide to migrating to Payload.
How to render rich text on your front end
Payload’s RichText component, from @payloadcms/richtext-lexical/react, turns the saved JSON into React. It renders the default nodes on its own. Three things need your input:
- Depth. Uploads and internal links need their documents populated, so query with enough
depth. - Internal links. Pass an
internalDocToHreffunction toLinkJSXConverter. Without it, internal links render as#and the console logs an error. - Blocks. Add a converter for every block and inline block slug. Payload can’t guess how your blocks should look.
For example, the journal’s article component renders the class button, the FAQ as an accordion with its structured data, and the oven temperatures:
import {
type JSXConvertersFunction,
LinkJSXConverter,
RichText,
} from '@payloadcms/richtext-lexical/react'
// FAQPage structured data from the block's own items. Escaping "<"
// keeps a stray "</script>" in an answer from closing the tag.
const faqJsonLd = (items) =>
JSON.stringify({
'@context': 'https://schema.org',
'@type': 'FAQPage',
mainEntity: items.map((item) => ({
'@type': 'Question',
name: item.question,
acceptedAnswer: { '@type': 'Answer', text: item.answer },
})),
}).replace(/</g, '\\u003c')
const converters: JSXConvertersFunction = ({ defaultConverters }) => ({
...defaultConverters,
...LinkJSXConverter({
internalDocToHref: ({ linkNode }) => {
const { relationTo, value } = linkNode.fields.doc!
const slug = typeof value === 'object' ? value.slug : ''
return relationTo === 'courses' ? `/courses/${slug}` : `/journal/${slug}`
},
}),
blocks: {
// BookClassButton is your own component
bookClass: ({ node }) => <BookClassButton {...node.fields} />,
faq: ({ node }) => (
<section>
{node.fields.items.map((item) => (
<details key={item.id}>
<summary>{item.question}</summary>
<p>{item.answer}</p>
</details>
))}
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: faqJsonLd(node.fields.items) }}
/>
</section>
),
},
inlineBlocks: {
ovenTemp: ({ node }) => (
<span>
{node.fields.celsius}°C ({Math.round(node.fields.celsius * 1.8 + 32)}°F)
</span>
),
},
})
export function Article({ post }) {
return <RichText converters={converters} data={post.content} />
}You can override any default converter the same way. A common one is upload, so images go through your site’s own image component. Fetching the post on a Next.js front end is covered in how Payload runs inside a Next.js app.
Converting rich text to HTML or plain text
When you need HTML, for an email, an RSS feed or a front end that isn’t React, convert it on demand with convertLexicalToHTML from @payloadcms/richtext-lexical/html. On the server, convertLexicalToHTMLAsync from /html-async with getPayloadPopulateFn fetches uploads and links as it goes.
For example, the cookery school’s weekly newsletter sends the latest post as HTML:
import escapeHTML from 'escape-html'
import { convertLexicalToHTML } from '@payloadcms/richtext-lexical/html'
const html = convertLexicalToHTML({
data: post.content,
converters: ({ defaultConverters }) => ({
...defaultConverters,
blocks: {
faq: ({ node }) =>
node.fields.items
.map((item) => `<h3>${escapeHTML(item.question)}</h3><p>${escapeHTML(item.answer)}</p>`)
.join(''),
},
}),
})The default converters escape text and only let web, email, phone and relative links through. A block converter returns your own string, so escape anything you insert, as the escape-html package does above.
The package also has lexicalHTMLField, which adds a hidden field holding the HTML. In 3.93.0 it converts on every read and saves nothing unless you set storeInDB, so the docs recommend converting on demand. For search indexes or meta descriptions, convertLexicalToPlaintext from /plaintext returns the text alone.
When to build a custom feature
A block or TextStateFeature covers most needs, and Payload’s custom features docs open by asking whether you need a feature at all. Build a feature when you need a new kind of node with its own editing behaviour, a toolbar button or a slash menu entry that does something blocks can’t.
A feature has two halves. The server half, made with createServerFeature, registers its nodes, Markdown transformers and translations. The client half adds what writers see, such as toolbar items, slash menu entries and Lexical plugins. For example, a "scale this recipe" button that multiplies every quantity in a list would be a feature, because it changes text that’s already in the editor.
Moving from Slate to Lexical
If your project still runs the Slate editor, migrate while you’re on Payload 3. Payload’s migration docs set out two phases:
- Preview. Add
SlateToLexicalFeatureto each rich text field. It converts Slate data to Lexical as it’s read, so you can check the admin, the API and your front end without changing the database. - Migrate. Run
migrateSlateToLexicalin a script, withdisableHooks: trueon the feature, to write the converted data. It covers every collection and global, every locale, and drafts as well as published documents.
Custom Slate nodes need converters of their own, which the docs show how to write. Run the migration on a copy of the database first.
What changes for rich text in Payload 4
Payload 4 is in beta, and the rich text changes below are from 4.0.0-beta.8 (10 November 2026) and Payload’s v4 migration guide. Betas can still change before 4.0 is stable, and our Payload review tracks the release.
- Slate removed. Lexical is the only rich text editor Payload ships. The Slate package is gone, and
@payloadcms/richtext-lexicalno longer has the migration utilities, so a Slate project migrates on Payload 3. - Tables renamed.
EXPERIMENTAL_TableFeaturebecomesTableFeature. - Legacy HTML converters removed.
HTMLConverterFeatureandlexicalHTMLare gone.convertLexicalToHTMLstays, imported from@payloadcms/richtext-lexical/html(beta.8 no longer exports it from the package root), andlexicalHTMLFieldstays. - Markdown on the upstream package. The editor uses
@lexical/markdowndirectly. If you call$convertFromMarkdownStringyourself, its defaults have changed, so useconvertMarkdownToLexicalwith your editor config. - Lexical upgraded. From 0.50.0 in richtext-lexical 3.93.0 to 0.53.0 in 4.0.0-beta.8.
The default features are the same 20 in both versions.
How we set up rich text on our builds
Our project template (v2.9.0, November 2026, on Payload 3.93.0) is what our client projects start from. It sets one editor at the config level, starting from the default features, with all six heading sizes, internal links to pages only, the relationship feature on and a required alt text on every image upload. Nothing from the opt-in group is added in the template itself.
No field overrides that editor, and the template puts no blocks inside rich text. Page sections live in the page’s blocks field, and rich text holds prose. A client project can still add its own features, such as blocks for that site, after the template’s.
Our own website has an FAQ block that can sit in a page’s layout or inside a post’s rich text body. The questions at the end of this guide are one, inside the article. The site builds the page’s FAQPage schema from that block’s own questions and answers.
Our Next.js front ends don’t use Payload’s RichText component. They share one renderer of our own that walks the Lexical JSON and outputs HTML for the node types the editor produces, including a relationship as a link to that page. HTML is never stored, so rich text stays as Lexical JSON and is turned into HTML at render time. Our renderer escapes all text, and it checks every link and image address so that only web, email and phone links and site-relative paths get through.
The only conversion runs outbound, in our workflow plugin’s send-email step, which turns its rich text body into HTML for the email. If you’d like an editor and front end shaped around how your team writes, our Payload CMS development team can help.
