Lexical Converters

Lexical saves data in JSON - this is great for storage and flexibility and allows you to easily to convert it to other formats like JSX, HTML or Markdown.

Lexical => JSX

If your frontend uses React, converting Lexical to JSX is the recommended way to render rich text content. Import the RichText component from @payloadcms/richtext-lexical/react and pass the Lexical content to it:

1import React from 'react'
2import { RichText } from '@payloadcms/richtext-lexical/react'
3import { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
4
5export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
6  return (
7    <RichText data={data} />
8  )
9}

The RichText component includes built-in serializers for common Lexical nodes but allows customization through the converters prop.

In our website template you have an example of how to use converters to render custom blocks.

Converting Lexical Blocks to JSX

In order to convert lexical blocks or inline blocks to JSX, you will have to pass the converter for your block to the RichText component. This converter is not included by default, as Payload doesn't know how to render your custom blocks.

1import React from 'react'
2import {
3  type JSXConvertersFunction,
4  RichText,
5} from '@payloadcms/richtext-lexical/react'
6import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
7
8const jsxConverters: JSXConvertersFunction = ({ defaultConverters }) => ({
9  ...defaultConverters,
10  blocks: {
11    // myTextBlock is the slug of the block
12    myTextBlock: ({ node }) => <div style={{ backgroundColor: 'red' }}>{node.fields.text}</div>,
13  },
14})
15
16export const MyComponent = ({ lexicalData }) => {
17  return (
18    <RichText
19      converters={jsxConverters}
20      data={lexicalData.lexicalWithBlocks as SerializedEditorState}
21    />
22  )
23}

Lexical => HTML

If you don't have a React-based frontend, or if you need to send the content to a third-party service, you can convert lexical to HTML. There are two ways to do this:

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.

In both cases, the conversion needs to happen on a server, as the HTML converter will automatically fetch data for nodes that require it (e.g. uploads and internal links). 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'
2
3import { HTMLConverterFeature, lexicalEditor, lexicalHTML } from '@payloadcms/richtext-lexical'
4
5const 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' }),
],
22}

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 the convertLexicalToHTML function:

1import { consolidateHTMLConverters, convertLexicalToHTML } from '@payloadcms/richtext-lexical'
2
3
4await convertLexicalToHTML({
5  converters: consolidateHTMLConverters({ editorConfig }),
6  data: editorData,
7  payload, // if you have Payload but no req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes)
8  req, // if you have req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes). No need to pass in Payload if req is passed in.
9})

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.

Example: Generating HTML within an afterRead hook

1import type { FieldHook } from 'payload'
2
3import {
4  HTMLConverterFeature,
5  consolidateHTMLConverters,
6  convertLexicalToHTML,
7  defaultEditorConfig,
8  defaultEditorFeatures,
9  sanitizeServerEditorConfig,
10} from '@payloadcms/richtext-lexical'
11
12const hook: FieldHook = async ({ req, siblingData }) => {
13  const editorConfig = defaultEditorConfig
14
15  editorConfig.features = [...defaultEditorFeatures, HTMLConverterFeature({})]
16
17  const sanitizedEditorConfig = await sanitizeServerEditorConfig(editorConfig, req.payload.config)
18
19  const html = await convertLexicalToHTML({
20    converters: consolidateHTMLConverters({ editorConfig: sanitizedEditorConfig }),
21    data: siblingData.lexicalSimple,
22    req,
23  })
24  return html
25}

CSS

Payload's lexical HTML converter does not generate CSS for you, but it does add classes to the generated HTML. You can use these classes to style the HTML in your frontend.

Here is some "base" CSS you can use to ensure that nested lists render correctly:

1/* Base CSS for Lexical HTML */
2.nestedListItem, .list-check {
3  list-style-type: none;
4}

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'
2
3const UploadHTMLConverter: HTMLConverter<SerializedUploadNode> = {
converter: async ({ node, req }) => {
  const uploadDocument: {
    value?: any
    } = {}
  if(req) {
    await populate({
      id,
      collectionSlug: node.relationTo,
      currentDepth: 0,
      data: uploadDocument,
      depth: 1,
      draft: false,
      key: 'value',
      overrideAccess: false,
      req,
      showHiddenFields: false,
    })
  }
22
  const url = (req?.payload?.config?.serverURL || '') + uploadDocument?.value?.url
24
  if (!(uploadDocument?.value?.mimeType as string)?.startsWith('image')) {
    // Only images can be serialized as HTML
    return ``
  }
29
  return `<img src="${url}" alt="${uploadDocument?.value?.filename}" width="${uploadDocument?.value?.width}"  height="${uploadDocument?.value?.height}"/>`
},
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.
33}

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 ServerFeature, allowing it to be handled automatically by the consolidateHTMLConverters function. Here is an example:

1import { createNode } from '@payloadcms/richtext-lexical'
2import type { FeatureProviderProviderServer } from '@payloadcms/richtext-lexical'
3
4export const UploadFeature: FeatureProviderProviderServer<
UploadFeatureProps,
UploadFeaturePropsClient
7> = (props) => {
/*...*/
return {
  feature: () => {
    return {
      nodes: [
        createNode({
          converters: {
            html: yourHTMLConverter, // <= This is where you define your HTML Converter
          },
          node: UploadNode,
          //...
        }),
      ],
      ClientComponent: UploadFeatureClientComponent,
      clientFeatureProps: clientProps,
      serverFeatureProps: props,
      /*...*/
    }
  },
  key: 'upload',
  serverFeatureProps: props,
}
30}

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 '@payloadcms/richtext-lexical/lexical/headless'
2import { getEnabledNodes, sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
3
4const yourEditorConfig // <= your editor config here
5const payloadConfig // <= your Payload Config here
6
7const headlessEditor = createHeadlessEditor({
8  nodes: getEnabledNodes({
9    editorConfig: sanitizeServerEditorConfig(yourEditorConfig, payloadConfig),
10  }),
11})

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]

Getting the editor config from an existing field

If you have access to the sanitized collection config, you can get access to the lexical sanitized editor config & features, as every lexical richText field returns it. Here is an example how you can get it from another field's afterRead hook:

1import type { CollectionConfig, RichTextField } from 'payload'
2import { createHeadlessEditor } from '@payloadcms/richtext-lexical/lexical/headless'
3import type { LexicalRichTextAdapter, SanitizedServerEditorConfig } from '@payloadcms/richtext-lexical'
4import {
getEnabledNodes,
lexicalEditor
7} from '@payloadcms/richtext-lexical'
8
9export const MyCollection: CollectionConfig = {
slug: 'slug',
fields: [
  {
    name: 'text',
    type: 'text',
    hooks: {
      afterRead: [
        ({ value, collection }) => {
          const otherRichTextField: RichTextField = collection.fields.find(
            (field) => 'name' in field && field.name === 'richText',
          ) as RichTextField
21
          const lexicalAdapter: LexicalRichTextAdapter =
            otherRichTextField.editor as LexicalRichTextAdapter
24
          const sanitizedServerEditorConfig: SanitizedServerEditorConfig =
            lexicalAdapter.editorConfig
27
          const headlessEditor = createHeadlessEditor({
            nodes: getEnabledNodes({
              editorConfig: sanitizedServerEditorConfig,
            }),
          })
33
          // Do whatever you want with the headless editor
35
          return value
        },
      ],
    },
  },
  {
    name: 'richText',
    type: 'richText',
    editor: lexicalEditor({
      features,
    }),
  }
]
49}

HTML => Lexical

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

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

Functions prefixed with a $ can only be run inside 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 { sanitizeServerEditorConfig, $convertFromMarkdownString } from '@payloadcms/richtext-lexical'
2
3const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & Payload Config here
4const markdown = `# Hello World`
5
6headlessEditor.update(
7  () => {
8    $convertFromMarkdownString(markdown, yourSanitizedEditorConfig.features.markdownTransformers)
9  },
10  { discrete: true },
11)
12
13// Do this if you then want to get the editor JSON
14const 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 '@payloadcms/richtext-lexical/lexical/markdown'
2import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
3import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
4
5const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & Payload Config here
6const yourEditorState: SerializedEditorState // <= your current editor state here
7
8// Import editor state into your headless editor
9try {
10  headlessEditor.update(
11    () => {
12      headlessEditor.setEditorState(headlessEditor.parseEditorState(yourEditorState))
13    },
14    { discrete: true },  // This should commit the editor state immediately
15  )
16} catch (e) {
17  logger.error({ err: e }, 'ERROR parsing editor state')
18}
19
20// Export to markdown
21let markdown: string
22headlessEditor.getEditorState().read(() => {
23  markdown = $convertToMarkdownString(yourSanitizedEditorConfig?.features?.markdownTransformers)
24})

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.