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.
If you have a React-based frontend, converting lexical to JSX is the recommended way to render rich text content in your frontend. To do that, import the RichText component from @payloadcms/richtext-lexical/react and pass the lexical content to it:
The RichText component will come with the most common serializers built-in, though you can also pass in your own serializers if you need to.
The JSX converter expects the input data to be fully populated. When fetching data, ensure the depth setting is high enough, to ensure that lexical nodes such as uploads are populated.
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.
1
importReactfrom'react'
2
import{
3
type JSXConvertersFunction,
4
RichText,
5
}from'@payloadcms/richtext-lexical/react'
6
import type {SerializedEditorState}from'@payloadcms/richtext-lexical/lexical'
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.
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.
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:
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:
1
import type {HTMLConverter}from'@payloadcms/richtext-lexical'
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.
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:
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:
1
import{ defaultEditorConfig, defaultEditorFeatures }from'@payloadcms/richtext-lexical'// <= make sure this package is installed
2
3
const yourEditorConfig = defaultEditorConfig
4
5
// If you made changes to the features of the field's editor config, you should also make those changes here:
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:
1
import type {CollectionConfig,RichTextField}from'payload'
Using the discrete: true flag ensures instant updates to the editor state. If
immediate reading of the updated state isn't necessary, you can omit the flag.