There are two main approaches to convert your Lexical-based rich text to HTML:
Generate HTML on-demand (Recommended): Convert JSON to HTML wherever you need it, on-demand.
Generate HTML within your Collection: Create a new field that automatically converts your saved JSON content to HTML. This is not recommended because it adds overhead to the Payload API.
To convert JSON to HTML on-demand, use the convertLexicalToHTML function from @payloadcms/richtext-lexical/html. Here's an example of how to use it in a React component in your frontend:
By default, convertLexicalToHTML expects fully populated data (e.g. uploads, links, etc.). If you need to dynamically fetch and populate those nodes, use the async variant, convertLexicalToHTMLAsync, from @payloadcms/richtext-lexical/html-async. You must provide a populate function:
exportconstMyComponent=({ data }:{ data:SerializedEditorState})=>{
10
const[html, setHTML]=useState<null|string>(null)
11
useEffect(()=>{
12
asyncfunctionconvert(){
13
const html =awaitconvertLexicalToHTMLAsync({
14
data,
15
populate:getRestPopulateFn({
16
apiURL:`http://localhost:3000/api`,
17
}),
18
})
19
setHTML(html)
20
}
21
22
voidconvert()
23
},[data])
24
25
return html &&<divdangerouslySetInnerHTML={{ __html: html }}/>
26
}
Using the REST populate function will send a separate request for each node. If you need to populate a large number of nodes, this may be slow. For improved performance on the server, you can use the getPayloadPopulateFn function:
The lexicalHTMLField() helper converts JSON to HTML and saves it in a field that is updated every time you read it via an afterRead hook. It's generally not recommended, as it creates a column with duplicate content in another format.
Important: When converting HTML to Lexical, <img> tags are NOT automatically uploaded. This is intentional because we don't know which uploads-enabled collection to add them to, and that collection may have required fields that cannot be auto-filled. Images will be omitted from the conversion unless you provide the proper data attributes. See Converting HTML with Images for guidance on handling images.
1
import{
2
convertHTMLToLexical,
3
editorConfigFactory,
4
}from'@payloadcms/richtext-lexical'
5
// Make sure you have jsdom and @types/jsdom installed
6
import{JSDOM}from'jsdom'
7
8
const lexicalJSON =convertHTMLToLexical({
9
editorConfig:await editorConfigFactory.default({
10
config,// Your Payload Config
11
}),
12
html:'<p>text</p>',
13
JSDOM,// Pass in the JSDOM import; it's not bundled to keep package size small
When converting HTML to Lexical, <img> tags require special handling because Payload does not automatically upload images to prevent unintended database modifications. Here are three approaches to handle images during HTML-to-Lexical conversion:
For bulk content migration or when dealing with external image URLs, parse the HTML first, upload images, then replace the image tags with proper attributes.
If you already have upload IDs and want to build the Lexical JSON structure, use the buildEditorState helper for a type-safe, simplified approach. This helper requires less boilerplate and eliminates the need to manually construct the root node.
Ensure images have both data-lexical-upload-id and data-lexical-upload-relation-to attributes
Verify the upload ID exists in your upload collection
Check that the relationTo value matches your upload collection slug
"Cannot read property 'id' of undefined" errors:
The upload document may not exist - verify the ID is correct
Ensure the upload collection is properly configured
Check that the referenced upload hasn't been deleted
Images work in the admin UI but not in conversion:
The admin UI handles pending uploads differently than server-side conversion
Server-side conversion requires existing upload IDs, not pending uploads
Always upload images before converting HTML
Tip: For large-scale content migrations, consider creating a migration script that processes HTML in batches, uploads images in parallel with rate limiting, and handles errors gracefully.