DEV Community

Amit Verma
Amit Verma

Posted on Originally published at tayloramitverma.com on

Payload CMS Rich Text That Editors Control: A Lexical Configuration Guide

Our editorial crew wanted more control inside Payload CMS, but we had to respect the design system. Give editors a blank canvas and you get five shades of red text and screenshots of code. Lock everything down and they paste HTML into a textarea. Turning the rich text editor into a guided experience solved the impasse.

This is how I configure Payload 3's Lexical editor today — including on this very blog.

Start with an audit, not a feature list

Before touching config, I exported the last 50 posts and listed what editors actually published:

  • Headings, lists, links, bold and inline code — every post.
  • Callout boxes ("Note", "Warning") — about a third of posts.
  • Code snippets with syntax highlighting — every technical post.
  • Images with captions — most posts.
  • Underline, subscript, superscript, text alignment — almost never, and usually by accident.

That list is the editor configuration. Everything on it becomes a supported feature or block; everything off it gets removed.

Remove what you don't support

Payload's Lexical editor ships with a generous set of default features. Each feature has a key, so trimming is a filter:

// fields/richText.ts
import {
  BlocksFeature,
  FixedToolbarFeature,
  HeadingFeature,
  lexicalEditor,
} from '@payloadcms/richtext-lexical'
import { Banner } from '@/blocks/Banner/config'
import { Code } from '@/blocks/Code/config'
import { MediaBlock } from '@/blocks/MediaBlock/config'

const UNSUPPORTED = ['underline', 'subscript', 'superscript', 'strikethrough', 'align', 'indent']

export const postEditor = lexicalEditor({
  features: ({ defaultFeatures }) => [
    ...defaultFeatures.filter((feature) => !UNSUPPORTED.includes(feature.key)),
    HeadingFeature({ enabledHeadingSizes: ['h2', 'h3', 'h4'] }),
    BlocksFeature({ blocks: [Banner, Code, MediaBlock] }),
    FixedToolbarFeature(),
  ],
})
Enter fullscreen mode Exit fullscreen mode

Two details worth calling out:

  • enabledHeadingSizes excludes h1 . The post title is the page's only h1. Letting editors add another one quietly hurts accessibility and SEO.
  • FixedToolbarFeature puts a toolbar at the top of the field. Editors who don't know the / slash menu exists still find every tool.

Turn editorial patterns into blocks

A callout is not "bold text in a coloured paragraph". It's a block with a fixed set of styles that map to design tokens:

// blocks/Banner/config.ts
import type { Block } from 'payload'
import { lexicalEditor } from '@payloadcms/richtext-lexical'

export const Banner: Block = {
  slug: 'banner',
  interfaceName: 'BannerBlock',
  fields: [
    {
      name: 'style',
      type: 'select',
      required: true,
      defaultValue: 'info',
      options: [
        { label: 'Info', value: 'info' },
        { label: 'Warning', value: 'warning' },
        { label: 'Success', value: 'success' },
      ],
    },
    { name: 'content', type: 'richText', required: true, editor: lexicalEditor() },
  ],
}
Enter fullscreen mode Exit fullscreen mode

Editors pick intent ("Warning"), not colours. When the design team changes what a warning looks like, every post updates at once.

Code snippets get the same treatment. A Code block with a language select and a code field (Payload's built-in Monaco editor) beats inline code pasted into a paragraph — whitespace survives, and the front end can syntax-highlight it.

// blocks/Code/config.ts
import type { Block } from 'payload'

export const Code: Block = {
  slug: 'code',
  interfaceName: 'CodeBlock',
  fields: [
    {
      name: 'language',
      type: 'select',
      required: true,
      defaultValue: 'typescript',
      options: ['typescript', 'javascript', 'python', 'bash', 'json'].map((v) => ({ label: v, value: v })),
    },
    { name: 'code', type: 'code', required: true },
  ],
}
Enter fullscreen mode Exit fullscreen mode

interfaceName matters: it makes payload generate:types emit a named BannerBlock / CodeBlock type, which you'll reuse on the front end.

Render blocks with JSX converters

On the Next.js side, @payloadcms/richtext-lexical/react renders the stored JSON. Each custom block gets a converter keyed by its slug:

// components/RichText.tsx
import type { DefaultNodeTypes, SerializedBlockNode } from '@payloadcms/richtext-lexical'
import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
import { type JSXConvertersFunction, RichText as LexicalRichText } from '@payloadcms/richtext-lexical/react'
import type { BannerBlock as BannerProps, CodeBlock as CodeProps } from '@/payload-types'
import { BannerBlock } from '@/blocks/Banner/Component'
import { CodeBlock } from '@/blocks/Code/Component'

type NodeTypes = DefaultNodeTypes | SerializedBlockNode<BannerProps | CodeProps>

const converters: JSXConvertersFunction<NodeTypes> = ({ defaultConverters }) => ({
  ...defaultConverters,
  blocks: {
    banner: ({ node }) => <BannerBlock {...node.fields} />,
    code: ({ node }) => <CodeBlock {...node.fields} />,
  },
})

export function RichText({ data }: { data: SerializedEditorState }) {
  return <LexicalRichText converters={converters} data={data} className="prose" />
}
Enter fullscreen mode Exit fullscreen mode

If an editor somehow inserts a block you haven't written a converter for, nothing renders for it — so add a converter in the same pull request that adds the block config.

Guardrails beyond the toolbar

Removing buttons covers most mistakes. A few more checks catch the rest:

  • Paste cleanup. Lexical can only create nodes the editor has registered, so pasted tables, embeds or stray HTML from Google Docs fall back to plain paragraphs instead of sneaking in. That's another reason to remove features instead of just hiding their buttons.
  • Validation. Rich text fields accept a validate function. We use it to reject posts that have no h2, which keeps long articles skimmable.
  • Live preview. Payload's live preview shows the real front-end rendering next to the editor, so editors see the design system instead of guessing at it.

The result

Training took twenty minutes because editors only see the controls we support. The content API stays predictable, the front end stays on brand, and new patterns arrive as a request for a block rather than a creative workaround.

We review the editor configuration every quarter and change it based on real posts, not hypothetical edge cases. Editors feel heard, and the codebase stays calm.


Originally published at www.tayloramitverma.com.

Top comments (0)