Converting HTML

Rich Text to HTML

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.

On-demand

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:

1'use client'
2
3import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
4import { convertLexicalToHTML } from '@payloadcms/richtext-lexical/html'
5
6import React from 'react'
7
8export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
9  const html = convertLexicalToHTML({ data })
10
11  return <div dangerouslySetInnerHTML={{ __html: html }} />
12}

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:

1'use client'
2
3import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
4
5import { getRestPopulateFn } from '@payloadcms/richtext-lexical/client'
6import { convertLexicalToHTMLAsync } from '@payloadcms/richtext-lexical/html-async'
7import React, { useEffect, useState } from 'react'
8
9export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
10  const [html, setHTML] = useState<null | string>(null)
11  useEffect(() => {
12    async function convert() {
13      const html = await convertLexicalToHTMLAsync({
14        data,
15        populate: getRestPopulateFn({
16          apiURL: `http://localhost:3000/api`,
17        }),
18      })
19      setHTML(html)
20    }
21
22    void convert()
23  }, [data])
24
25  return html && <div dangerouslySetInnerHTML={{ __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:

1import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
2
3import { getPayloadPopulateFn } from '@payloadcms/richtext-lexical'
4import { convertLexicalToHTMLAsync } from '@payloadcms/richtext-lexical/html-async'
5import { getPayload } from 'payload'
6import React from 'react'
7
8import config from '../../config.js'
9
10export const MyRSCComponent = async ({
11  data,
12}: {
13  data: SerializedEditorState
14}) => {
15  const payload = await getPayload({
16    config,
17  })
18
19  const html = await convertLexicalToHTMLAsync({
20    data,
21    populate: await getPayloadPopulateFn({
22      currentDepth: 0,
23      depth: 1,
24      payload,
25    }),
26  })
27
28  return html && <div dangerouslySetInnerHTML={{ __html: html }} />
29}

HTML field

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.

Consider using the on-demand HTML converter above or the JSX converter unless you have a good reason.

1import type { HTMLConvertersFunction } from '@payloadcms/richtext-lexical/html'
2import type { MyTextBlock } from '@/payload-types.js'
3import type { CollectionConfig } from 'payload'
4
5import {
BlocksFeature,
type DefaultNodeTypes,
lexicalEditor,
lexicalHTMLField,
type SerializedBlockNode,
11} from '@payloadcms/richtext-lexical'
12
13const Pages: CollectionConfig = {
slug: 'pages',
fields: [
  {
    name: 'nameOfYourRichTextField',
    type: 'richText',
    editor: lexicalEditor(),
  },
  lexicalHTMLField({
    htmlFieldName: 'nameOfYourRichTextField_html',
    lexicalFieldName: 'nameOfYourRichTextField',
  }),
  {
    name: 'customRichText',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ defaultFeatures }) => [
        ...defaultFeatures,
        BlocksFeature({
          blocks: [
            {
              interfaceName: 'MyTextBlock',
              slug: 'myTextBlock',
              fields: [
                {
                  name: 'text',
                  type: 'text',
                },
              ],
            },
          ],
        }),
      ],
    }),
  },
  lexicalHTMLField({
    htmlFieldName: 'customRichText_html',
    lexicalFieldName: 'customRichText',
    // can pass in additional converters or override default ones
    converters: (({ defaultConverters }) => ({
      ...defaultConverters,
      blocks: {
        myTextBlock: ({ node, providedCSSString }) =>
          `<div style="background-color: red;${providedCSSString}">${node.fields.text}</div>`,
      },
    })) as HTMLConvertersFunction<
      DefaultNodeTypes | SerializedBlockNode<MyTextBlock>
    >,
  }),
],
63}

Blocks to HTML

If your rich text includes Lexical blocks, you need to provide a way to convert them to HTML. For example:

1'use client'
2
3import type { MyInlineBlock, MyTextBlock } from '@/payload-types'
4import type {
5  DefaultNodeTypes,
6  SerializedBlockNode,
7  SerializedInlineBlockNode,
8} from '@payloadcms/richtext-lexical'
9import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
10
11import {
12  convertLexicalToHTML,
13  type HTMLConvertersFunction,
14} from '@payloadcms/richtext-lexical/html'
15import React from 'react'
16
17type NodeTypes =
18  | DefaultNodeTypes
19  | SerializedBlockNode<MyTextBlock>
20  | SerializedInlineBlockNode<MyInlineBlock>
21
22const htmlConverters: HTMLConvertersFunction<NodeTypes> = ({
23  defaultConverters,
24}) => ({
25  ...defaultConverters,
26  blocks: {
27    // Each key should match your block's slug
28    myTextBlock: ({ node, providedCSSString }) =>
29      `<div style="background-color: red;${providedCSSString}">${node.fields.text}</div>`,
30  },
31  inlineBlocks: {
32    // Each key should match your inline block's slug
33    myInlineBlock: ({ node, providedStyleTag }) =>
34      `<span${providedStyleTag}>${node.fields.text}</span$>`,
35  },
36})
37
38export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
39  const html = convertLexicalToHTML({
40    converters: htmlConverters,
41    data,
42  })
43
44  return <div dangerouslySetInnerHTML={{ __html: html }} />
45}

HTML to Richtext

If you need to convert raw HTML into a Lexical editor state, use convertHTMLToLexical from @payloadcms/richtext-lexical, along with the editorConfigFactory to retrieve the editor config:

1import {
2  convertHTMLToLexical,
3  editorConfigFactory,
4} from '@payloadcms/richtext-lexical'
5// Make sure you have jsdom and @types/jsdom installed
6import { JSDOM } from 'jsdom'
7
8const html = 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
14})

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."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.