You are currently viewing documentation for the docs/lexical-blocks branch.
Blocks
The BlocksFeature allows you to embed Payload's Blocks Field directly inside your Lexical rich text editor. This provides a powerful way to create structured, reusable content components within your rich text content.
Blocks within Lexical support the same features as standard Payload blocks—including all field types, hooks, validation, access control, and conditional logic. The only difference is that the data is stored within the rich text JSON structure rather than as separate fields.
Inline blocks can be inserted within text, appearing alongside other content in the same paragraph. They're useful for elements that need to flow with text.
You can customize how blocks appear in the editor by providing custom React components. This is useful when you want a more visual representation of your block content.
Your custom component can use composable primitives from @payloadcms/richtext-lexical/client. These components automatically receive block data from context, so you can use them to recreate the default block UI or arrange them in custom layouts:
You can manually render the remove and edit buttons if you want to:
19
</div>
20
<divstyle={{ display:'flex'}}>
21
<BlockEditButton/>
22
<BlockRemoveButton/>
23
</div>
24
</BlockCollapsible>
25
)
26
}
The BlockCollapsible component automatically renders an edit button that opens a drawer with the block's fields. You can customize this behavior by passing props like removeButton={false} to hide the default remove button and render it yourself.
You can also choose to render something completely different in your custom block component:
You can also customize the label shown in the block header using admin.components.Label. This is useful for displaying dynamic information based on the block's field values.
For a real-world example of a custom block component, see the source code for Payload's pre-made CodeBlock. It's a standard block with a custom admin.components.Block component that uses the same APIs documented above—including useFormFields, BlockCollapsible, and the helper buttons.
Payload provides a pre-built CodeBlock that you can use directly in your projects. It includes syntax highlighting, language selection, and optional TypeScript type definitions support: