Payload CMS rich text editor: Lexical features, blocks and rendering

Idea Labz · Nov 16, 2026 · 13 min read

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.

FeatureOn by defaultWhat it addsMarkdown shortcut
BoldFeature, ItalicFeature, UnderlineFeature, StrikethroughFeature, SubscriptFeature, SuperscriptFeature, InlineCodeFeatureyestext formats**bold**, *italic*, ~~strike~~, `code`
ParagraphFeatureyesparagraph entries in the menusnone
HeadingFeatureyesH1 to H6, or the sizes you list# to ######
AlignFeatureyesleft, centre, right, justifynone
IndentFeatureyesindenting with Tabnone
UnorderedListFeatureyesbulleted lists-, * or +
OrderedListFeatureyesnumbered lists1.
ChecklistFeatureyeschecklists- [ ] and - [x]
LinkFeatureyesexternal links and links to documents[text](url)
RelationshipFeatureyesa block that points at another documentnone
BlockquoteFeatureyesquotes>
UploadFeatureyesan image or file from an upload collectionnone
HorizontalRuleFeatureyesa divider---
InlineToolbarFeatureyesa toolbar on selected textnone
FixedToolbarFeaturenoa toolbar pinned above the editornone
BlocksFeaturenoyour own blocks and inline blocksnone
EXPERIMENTAL_TableFeaturenotablesnone
TextStateFeaturenocolours and styles on textnone
TreeViewFeaturenoa debug panel showing the editor statenone

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:

  1. Depth. Uploads and internal links need their documents populated, so query with enough depth.
  2. Internal links. Pass an internalDocToHref function to LinkJSXConverter. Without it, internal links render as # and the console logs an error.
  3. 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:

  1. Preview. Add SlateToLexicalFeature to 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.
  2. Migrate. Run migrateSlateToLexical in a script, with disableHooks: true on 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-lexical no longer has the migration utilities, so a Slate project migrates on Payload 3.
  • Tables renamed. EXPERIMENTAL_TableFeature becomes TableFeature.
  • Legacy HTML converters removed. HTMLConverterFeature and lexicalHTML are gone. convertLexicalToHTML stays, imported from @payloadcms/richtext-lexical/html (beta.8 no longer exports it from the package root), and lexicalHTMLField stays.
  • Markdown on the upstream package. The editor uses @lexical/markdown directly. If you call $convertFromMarkdownString yourself, its defaults have changed, so use convertMarkdownToLexical with 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.

Frequently asked questions

Is Payload’s rich text editor free?

Yes. @payloadcms/richtext-lexical is MIT licensed, like Payload itself, and its features and converters are all part of that open-source package.

Does Payload have a visual editor?

Payload’s Enterprise Visual Editor, for editing a page directly on the website, is still to come as of 13 November 2026. In the open-source core, Live Preview shows your real front end beside the edit view while writers work, and our guide to drafts and Live Preview covers the setup.

Can I store HTML instead of JSON?

Not in the rich text field, which always saves Lexical JSON. Convert to HTML when you render, or add lexicalHTMLField if an outside system needs HTML on every read.

How do I add a table to Payload’s rich text?

Add EXPERIMENTAL_TableFeature() to the field’s features in Payload 3, and both of Payload’s converters render the tables. In Payload 4 the feature is called TableFeature.

Can I write Markdown in Payload?

Yes. Writers can type shortcuts such as ## and -, and convertMarkdownToLexical and convertLexicalToMarkdown import and export Markdown with your editor config.

How do I render Payload rich text in Next.js?

Use the RichText component from @payloadcms/richtext-lexical/react. Query with enough depth, give LinkJSXConverter an internalDocToHref function, and add a converter for each of your blocks.

Can I use another editor, such as Tiptap?

You can, as a custom field. Tiptap or any other editor goes in as your own field component that stores its own format, such as HTML in a textarea field. You then build its admin features and its rendering yourself, because Payload’s features, blocks and converters only work with its Lexical editor.

Can I still use the Slate editor?

In Payload 3, yes, but it’s deprecated. Payload 4 removes it and the migration tools, so migrate on Payload 3.

What to do next

Set the config-level editor to what most of your rich text fields need, and add the rest per field with rootFeatures. Define each block once and offer it to both your layouts and the editor wherever writers need it. Before you publish, check that every block, inline block and internal link has a converter on your front end. If any content is still on Slate, migrate it on Payload 3.

If you’re choosing between rich text and other field types for your content, read our guide to Payload’s field types. If you haven’t set up a project yet, build one with our tutorial.

References

All links checked and active as of 13 November 2026.

READY TO MAKE A REAL CHANGE?

Let's build it together