Lexical Rich Text

One of Payload's goals is to build the best rich text editor experience that we possibly can. We want to combine the beauty and polish of the Medium editing experience with the strength and features of the Notion editor - all in one place.

Classically, we've used SlateJS to work toward this goal, but building custom elements into Slate has proven to be more difficult than we'd like, and we've been keeping our options open.

Lexical is extremely impressive and trivializes a lot of the hard parts of building new elements into a rich text editor. It has a few distinct advantages over Slate, including the following:

A "/" menu, which allows editors to easily add new elements while never leaving their keyboard
A "hover" toolbar that pops up if you select text
It supports Payload blocks natively, directly within your rich text editor
Custom elements, called "features", are much easier to build in Lexical vs. Slate

To use the Lexical editor, first you need to install it:

1npm install @payloadcms/richtext-lexical

Once you have it installed, you can pass it to your top-level Payload config as follows:

1import { buildConfig } from 'payload/config'
2import { lexicalEditor } from '@payloadcms/richtext-lexical'
3
4export default buildConfig({
5  collections: [
6    // your collections here
7  ],
8  // Pass the Lexical editor to the root config
9  editor: lexicalEditor({})
10})

You can also override Lexical settings on a field-by-field basis as follows:

1import type { CollectionConfig } from 'payload/types'
2import {
3  lexicalEditor
4} from '@payloadcms/richtext-lexical'
5
6export const Pages: CollectionConfig = {
7  slug: 'pages',
8  fields: [
9    {
10      name: 'content',
11      type: 'richText',
12      // Pass the Lexical editor here and override base settings as necessary
13      editor: lexicalEditor({})
14    }
15  ]
16}

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:

1import {
BlocksFeature,
LinkFeature,
UploadFeature,
lexicalEditor
6} from '@payloadcms/richtext-lexical'
7import { Banner } from '../blocks/Banner'
8import { CallToAction } from '../blocks/CallToAction'
9
10{
editor: lexicalEditor({
  features: ({ defaultFeatures }) => [
    ...defaultFeatures,
    LinkFeature({
      // Example showing how to customize the built-in fields
      // of the Link feature
      fields: [
        {
          name: 'rel',
          label: 'Rel Attribute',
          type: 'select',
          hasMany: true,
          options: ['noopener', 'noreferrer', 'nofollow'],
          admin: {
            description:
              'The rel attribute defines the relationship between a linked resource and the current document. This is a custom link field.',
          },
        },
      ],
    }),
    UploadFeature({
      collections: {
        uploads: {
          // Example showing how to customize the built-in fields
          // of the Upload feature
          fields: [
            {
              name: 'caption',
              type: 'richText',
              editor: lexicalEditor(),
            },
          ],
        },
      },
    }),
    // This is incredibly powerful. You can re-use your Payload blocks
    // directly in the Lexical editor as follows:
    BlocksFeature({
      blocks: [
        Banner,
        CallToAction,
      ],
    }),
  ]
})
56}

Features overview

Here's an overview of all the included features:

Feature Name	Included by default	Description
`BoldTextFeature`	Yes	Handles the bold text format
`ItalicTextFeature`	Yes	Handles the italic text format
`UnderlineTextFeature`	Yes	Handles the underline text format
`StrikethroughTextFeature`	Yes	Handles the strikethrough text format
`SubscriptTextFeature`	Yes	Handles the subscript text format
`SuperscriptTextFeature`	Yes	Handles the superscript text format
`InlineCodeTextFeature`	Yes	Handles the inline-code text format
`ParagraphFeature`	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
`HeadingFeature`	Yes	Adds Heading Nodes (by default, H1 - H6, but that can be customized)
`AlignFeature`	Yes	Allows you to align text left, centered and right
`IndentFeature`	Yes	Allows you to indent text with the tab key
`UnorderedListFeature`	Yes	Adds unordered lists (ul)
`OrderedListFeature`	Yes	Adds ordered lists (ol)
`CheckListFeature`	Yes	Adds checklists
`LinkFeature`	Yes	Allows you to create internal and external links
`RelationshipFeature`	Yes	Allows you to create block-level (not inline) relationships to other documents
`BlockQuoteFeature`	Yes	Allows you to create block-level quotes
`UploadFeature`	Yes	Allows you to create block-level upload nodes - this supports all kinds of uploads, not just images
`HorizontalRuleFeature`	Yes	Horizontal rules / separators. Basically displays an `<hr>` element
`BlocksFeature`	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.
`TreeViewFeature`	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

Creating your own, custom Feature

Creating your own custom feature requires deep knowledge of the Lexical editor. We recommend you take a look at the Lexical documentation first - especially the "concepts" section.

Next, take a look at the features we've already built - understanding how they work will help you understand how to create your own. There is no difference between the features included by default and the ones you create yourself - since those features are all isolated from the "core", you have access to the same APIs, whether the feature is part of payload or not!

Converters

Lexical => HTML

Lexical saves data in JSON, but can also generate its HTML representation via two main methods:

Outputting HTML from the Collection: Create a new field in your collection to convert saved JSON content to HTML. Payload generates and outputs the HTML for use in your frontend.
Generating HTML on any server Convert JSON to HTML on-demand on the server.

The editor comes with built-in HTML serializers, simplifying the process of converting JSON to HTML.

Outputting HTML from the Collection

To add HTML generation directly within the collection, follow the example below:

1import type { CollectionConfig } from 'payload/types'
2
3import {
HTMLConverterFeature,
lexicalEditor,
lexicalHTML
7} from '@payloadcms/richtext-lexical'
8
9const Pages: CollectionConfig = {
slug: 'pages',
fields: [
  {
    name: 'nameOfYourRichTextField',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ defaultFeatures }) => [
        ...defaultFeatures,
        // The HTMLConverter Feature is the feature which manages the HTML serializers.
        // If you do not pass any arguments to it, it will use the default serializers.
        HTMLConverterFeature({}),
      ],
    }),
  },
  lexicalHTML('nameOfYourRichTextField', { name: 'nameOfYourRichTextField_html' }),
],
26}

The lexicalHTML() function creates a new field that automatically converts the referenced lexical richText field into HTML through an afterRead hook.

Generating HTML anywhere on the server:

If you wish to convert JSON to HTML ad-hoc, use this code snippet:

1import type { SerializedEditorState } from 'lexical'
2import {
3  type SanitizedEditorConfig,
4  convertLexicalToHTML,
5  consolidateHTMLConverters,
6} from '@payloadcms/richtext-lexical'
7
8async function lexicalToHTML(editorData: SerializedEditorState, editorConfig: SanitizedEditorConfig) {
9  return await convertLexicalToHTML({
10    converters: consolidateHTMLConverters({ editorConfig }),
11    data: editorData,
12  })
13}

This method employs convertLexicalToHTML from @payloadcms/richtext-lexical, which converts the serialized editor state into HTML.

Because every Feature is able to provide html converters, and because the htmlFeature can modify those or provide their own, we need to consolidate them with the default html Converters using the consolidateHTMLConverters function.

Creating your own HTML Converter

HTML Converters are typed as HTMLConverter, which contains the node type it should handle, and a function that accepts the serialized node from the lexical editor, and outputs the HTML string. Here's the HTML Converter of the Upload node as an example:

1import type { HTMLConverter } from '@payloadcms/richtext-lexical'
2import payload from 'payload'
3
4const UploadHTMLConverter: HTMLConverter<SerializedUploadNode> = {
5  converter: async ({ node }) => {
6    const uploadDocument = await payload.findByID({
7      id: node.value.id,
8      collection: node.relationTo,
9    })
10    const url = (payload?.config?.serverURL || '') + uploadDocument?.url
11
12    if (!(uploadDocument?.mimeType as string)?.startsWith('image')) {
13      // Only images can be serialized as HTML
14      return ``
15    }
16
17    return `<img src="${url}" alt="${uploadDocument?.filename}" width="${uploadDocument?.width}"  height="${uploadDocument?.height}"/>`
18  },
19  nodeTypes: [UploadNode.getType()], // This is the type of the lexical node that this converter can handle. Instead of hardcoding 'upload' we can get the node type directly from the UploadNode, since it's static.
20}

As you can see, we have access to all the information saved in the node (for the Upload node, this is valueand relationTo) and we can use that to generate the HTML.

The convertLexicalToHTML is part of @payloadcms/richtext-lexical automatically handles traversing the editor state and calling the correct converter for each node.

Embedding the HTML Converter in your Feature

You can embed your HTML Converter directly within your custom Feature, allowing it to be handled automatically by the consolidateHTMLConverters function. Here is an example:

1export const UploadFeature = (props?: UploadFeatureProps): FeatureProvider => {
return {
  feature: () => {
    return {
      nodes: [
        {
          converters: {
            html: yourHTMLConverter, // <= This is where you define your HTML Converter
          },
          node: UploadNode,
          type: UploadNode.getType(),
          //...
        },
      ],
      plugins: [/*...*/],
      props: props,
      slashMenu: {/*...*/},
    }
  },
  key: 'upload',
}
22}

Headless Editor

Lexical provides a seamless way to perform conversions between various other formats:

HTML to Lexical (or, importing HTML into the lexical editor)
Markdown to Lexical (or, importing Markdown into the lexical editor)
Lexical to Markdown

A headless editor can perform such conversions outside of the main editor instance. Follow this method to initiate a headless editor:

1import { createHeadlessEditor } from '@lexical/headless' // <= make sure this package is installed
2import {
3  getEnabledNodes,
4  sanitizeEditorConfig,
5} from '@payloadcms/richtext-lexical'
6
7const yourEditorConfig; // <= your editor config here
8
9const headlessEditor = createHeadlessEditor({
10  nodes: getEnabledNodes({
11    editorConfig: sanitizeEditorConfig(yourEditorConfig),
12  }),
13})

Getting the editor config

As you can see, you need to provide an editor config in order to create a headless editor. This is because the editor config is used to determine which nodes & features are enabled, and which converters are used.

To get the editor config, simply import the default editor config and adjust it - just like you did inside of the editor: lexicalEditor({}) property:

1import { defaultEditorConfig, defaultEditorFeatures } from '@payloadcms/richtext-lexical' // <= make sure this package is installed
2
3const yourEditorConfig = defaultEditorConfig
4
5// If you made changes to the features of the field's editor config, you should also make those changes here:
6yourEditorConfig.features = [
7  ...defaultEditorFeatures,
8  // Add your custom features here
9]

HTML => Lexical

Once you have your headless editor instance, you can use it to convert HTML to Lexical:

1import { $generateNodesFromDOM } from '@lexical/html'
2import { $getRoot,$getSelection } from 'lexical'
3import { JSDOM } from 'jsdom';
4
5headlessEditor.update(() => {
6  // In a headless environment you can use a package such as JSDom to parse the HTML string.
7  const dom = new JSDOM(htmlString)
8
9  // Once you have the DOM instance it's easy to generate LexicalNodes.
10  const nodes = $generateNodesFromDOM(headlessEditor, dom.window.document)
11
12  // Select the root
13  $getRoot().select()
14
15  // Insert them at a selection.
16  const selection = $getSelection()
17  selection.insertNodes(nodes)
18}, { discrete: true })
19
20// Do this if you then want to get the editor JSON
21const editorJSON = headlessEditor.getEditorState().toJSON()

Functions prefixed with a $ can only be run inside of an editor.update() or editorState.read() callback.

This has been taken from the lexical serialization & deserialization docs.

Markdown => Lexical

Convert markdown content to the Lexical editor format with the following:

1import { $convertFromMarkdownString } from '@lexical/markdown'
2import { sanitizeEditorConfig } from '@payloadcms/richtext-lexical'
3
4const yourSanitizedEditorConfig = sanitizeEditorConfig(yourEditorConfig) // <= your editor config here
5const markdown = `# Hello World`
6
7headlessEditor.update(() => { $convertFromMarkdownString(markdown, yourSanitizedEditorConfig.features.markdownTransformers) }, { discrete: true })
8
9// Do this if you then want to get the editor JSON
10const editorJSON = headlessEditor.getEditorState().toJSON()

Lexical => Markdown

Export content from the Lexical editor into Markdown format using these steps:

Import your current editor state into the headless editor.
Convert and fetch the resulting markdown string.

Here's the code for it:

1import { $convertToMarkdownString } from '@lexical/markdown'
2import { sanitizeEditorConfig } from '@payloadcms/richtext-lexical'
3import type { SerializedEditorState } from "lexical"
4
5const yourSanitizedEditorConfig = sanitizeEditorConfig(yourEditorConfig) // <= your editor config here
6const yourEditorState: SerializedEditorState // <= your current editor state here
7
8// Import editor state into your headless editor
9try {
10  headlessEditor.setEditorState(headlessEditor.parseEditorState(yourEditorState)) // This should commit the editor state immediately
11} catch (e) {
12  logger.error({ err: e }, 'ERROR parsing editor state')
13}
14
15// Export to markdown
16let markdown: string
17headlessEditor.getEditorState().read(() => {
18  markdown = $convertToMarkdownString(yourSanitizedEditorConfig?.features?.markdownTransformers)
19})

The .setEditorState() function immediately updates your editor state. Thus, there's no need for the discrete: true flag when reading the state afterward.

Lexical => Plain Text

Export content from the Lexical editor into plain text using these steps:

Import your current editor state into the headless editor.
Convert and fetch the resulting plain text string.

Here's the code for it:

1import type { SerializedEditorState } from "lexical"
2import { $getRoot } from "lexical"
3
4const yourEditorState: SerializedEditorState // <= your current editor state here
5
6// Import editor state into your headless editor
7try {
8  headlessEditor.setEditorState(headlessEditor.parseEditorState(yourEditorState)) // This should commit the editor state immediately
9} catch (e) {
10  logger.error({ err: e }, 'ERROR parsing editor state')
11}
12
13// Export to plain text
14const plainTextContent = headlessEditor.getEditorState().read(() => {
15  return $getRoot().getTextContent()
16}) || ''

Migrating from Slate

While both Slate and Lexical save the editor state in JSON, the structure of the JSON is different.

Migration via SlateToLexicalFeature

One way to handle this is to just give your lexical editor the ability to read the slate JSON.

Simply add the SlateToLexicalFeature to your editor:

1import type { CollectionConfig } from 'payload/types'
2
3import {
4  SlateToLexicalFeature,
5  lexicalEditor,
6} from '@payloadcms/richtext-lexical'
7
8const Pages: CollectionConfig = {
9  slug: 'pages',
10  fields: [
11    {
12      name: 'nameOfYourRichTextField',
13      type: 'richText',
14      editor: lexicalEditor({
15        features: ({ defaultFeatures }) => [
16          ...defaultFeatures,
17          SlateToLexicalFeature({})
18        ],
19      }),
20    },
21  ],
22}

and done! Now, everytime this lexical editor is initialized, it converts the slate date to lexical on-the-fly. If the data is already in lexical format, it will just pass it through.

This is by far the easiest way to migrate from Slate to Lexical, although it does come with a few caveats:

There is a performance hit when initializing the lexical editor
The editor will still output the Slate data in the output JSON, as the on-the-fly converter only runs for the admin panel

The easy way to solve this: Just save the document! This overrides the slate data with the lexical data, and the next time the document is loaded, the lexical data will be used. This solves both the performance and the output issue for that specific document.

Migration via migration script

The method described above does not solve the issue for all documents, though. If you want to convert all your documents to lexical, you can use a migration script. Here's a simple example:

1import type { Payload } from 'payload'
2import type { YourDocumentType } from 'payload/generated-types'
3
4import {
5  cloneDeep,
6  convertSlateToLexical,
7  defaultSlateConverters,
8} from '@payloadcms/richtext-lexical'
9
10import { AnotherCustomConverter } from './lexicalFeatures/converters/AnotherCustomConverter'
11
12export async function convertAll(payload: Payload, collectionName: string, fieldName: string) {
13  const docs: YourDocumentType[] = await payload.db.collections[collectionName].find({}).exec() // Use MongoDB models directly to query all documents at once
14  console.log(`Found ${docs.length} ${collectionName} docs`)
15
16  const converters = cloneDeep([...defaultSlateConverters, AnotherCustomConverter])
17
18  // Split docs into batches of 20.
19  const batchSize = 20
20  const batches = []
21  for (let i = 0; i < docs.length; i += batchSize) {
22    batches.push(docs.slice(i, i + batchSize))
23  }
24
25  let processed = 0 // Number of processed docs
26
27  for (const batch of batches) {
28    // Process each batch asynchronously
29    const promises = batch.map(async (doc: YourDocumentType) => {
30      const richText = doc[fieldName]
31
32      if (richText && Array.isArray(richText) && !('root' in richText)) { // It's Slate data - skip already-converted data
33        const converted = convertSlateToLexical({
34          converters: converters,
35          slateData: richText,
36        })
37
38        await payload.update({
39          id: doc.id,
40          collection: collectionName as any,
41          data: {
42            [fieldName]: converted,
43          },
44        })
45      }
46    })
47
48    // Wait for all promises in the batch to complete. Resolving batches of 20 asynchronously is faster than waiting for each doc to update individually
49    await Promise.all(promises)
50
51    // Update the count of processed docs
52    processed += batch.length
53    console.log(`Converted ${processed} of ${docs.length}`)
54  }
55}

The convertSlateToLexical is the same method used in the SlateToLexicalFeature - it handles traversing the Slate JSON for you.

Do note that this script might require adjustment depending on your document structure, especially if you have nested richText fields or localization enabled.

Converting custom Slate nodes

If you have custom Slate nodes, create a custom converter for them. Here's the Upload converter as an example:

1import type { SerializedUploadNode } from '../uploadNode.'
2import type { SlateNodeConverter } from '@payloadcms/richtext-lexical'
3
4export const SlateUploadConverter: SlateNodeConverter = {
converter({ slateNode }) {
  return {
    fields: {
      ...slateNode.fields,
    },
    format: '',
    relationTo: slateNode.relationTo,
    type: 'upload',
    value: {
      id: slateNode.value?.id || '',
    },
    version: 1,
  } as const as SerializedUploadNode
},
nodeTypes: ['upload'],
20}

It's pretty simple: You get a Slate node as input, and you return the lexical node. The nodeTypes array is used to determine which Slate nodes this converter can handle.

When using a migration script, you can add your custom converters to the converters property of the convertSlateToLexical props, as seen in the example above

When using the SlateToLexicalFeature, you can add your custom converters to the converters property of the SlateToLexicalFeature props:

1import type { CollectionConfig } from 'payload/types'
2
3import {
SlateToLexicalFeature,
lexicalEditor,
defaultSlateConverters
7} from '@payloadcms/richtext-lexical'
8
9import { YourCustomConverter } from '../converters/YourCustomConverter'
10
11const Pages: CollectionConfig = {
slug: 'pages',
fields: [
  {
    name: 'nameOfYourRichTextField',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ defaultFeatures }) => [
        ...defaultFeatures,
        SlateToLexicalFeature({
          converters: [
            ...defaultSlateConverters,
            YourCustomConverter
          ]
        }),
      ],
    }),
  },
],
30}

Migrating from payload-plugin-lexical

Migrating from payload-plugin-lexical works similar to migrating from Slate.

Instead of a SlateToLexicalFeature there is a LexicalPluginToLexicalFeature you can use. And instead of convertSlateToLexical you can use convertLexicalPluginToLexical.

Coming Soon

Lots more documentation will be coming soon, which will show in detail how to create your own custom features within Lexical.

For now, take a look at the TypeScript interfaces and let us know if you need a hand. Much more will be coming from the Payload team on this topic soon.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.