|
| 1 | +--- |
| 2 | +title: Rendering On Demand |
| 3 | +label: Rendering On Demand |
| 4 | +order: 50 |
| 5 | +desc: Rendering rich text on demand |
| 6 | +keywords: lexical, rich text, editor, headless cms, render, rendering |
| 7 | +--- |
| 8 | + |
| 9 | +Lexical in Payload is a **React Server Component (RSC)**. Historically that created three headaches: 1. You couldn't render the editor directly from the client. 2. Features like blocks, tables and link drawers require the server to know the shape of nested sub-fields at render time. If you tried to render on demand, the server didn't know those schemas. 3. The rich text field is designed to live inside a `Form`. For simple use cases, setting up a full form just to manage editor state was cumbersome. |
| 10 | + |
| 11 | +To simplify rendering richtext on demand, <RenderLexical />, that renders a Lexical editor while still covering the full feature set. On mount, it calls a server action to render the editor on the server using the new `render-field` server function. That server render gives Lexical everything it needs (including nested field schemas) and returns a ready-to-hydrate editor. |
| 12 | + |
| 13 | +<Banner type="warning"> |
| 14 | + `RenderLexical` and the underlying `render-field` server function are |
| 15 | + experimental and may change in minor releases. |
| 16 | +</Banner> |
| 17 | + |
| 18 | +## Inside an existing Form |
| 19 | + |
| 20 | +If you have an existing Form and want to render a richtext field within it, you can use the `RenderLexical` component like this: |
| 21 | + |
| 22 | +```tsx |
| 23 | +'use client' |
| 24 | + |
| 25 | +import type { JSONFieldClientComponent } from 'payload' |
| 26 | + |
| 27 | +import { |
| 28 | + buildEditorState, |
| 29 | + RenderLexical, |
| 30 | +} from '@payloadcms/richtext-lexical/client' |
| 31 | + |
| 32 | +import { lexicalFullyFeaturedSlug } from '../../slugs.js' |
| 33 | + |
| 34 | +export const Component: JSONFieldClientComponent = (args) => { |
| 35 | + return ( |
| 36 | + <RenderLexical |
| 37 | + field={{ |
| 38 | + name: 'myFieldName' /* Make sure this matches the field name present in your form */, |
| 39 | + }} |
| 40 | + initialValue={buildEditorState({ text: 'default value' })} |
| 41 | + schemaPath={`collection.${lexicalFullyFeaturedSlug}.richText`} |
| 42 | + /> |
| 43 | + ) |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +## Outside of a Form (you control state) |
| 48 | + |
| 49 | +```tsx |
| 50 | +'use client' |
| 51 | + |
| 52 | +import type { DefaultTypedEditorState } from '@payloadcms/richtext-lexical' |
| 53 | +import type { JSONFieldClientComponent } from 'payload' |
| 54 | + |
| 55 | +import { |
| 56 | + buildEditorState, |
| 57 | + RenderLexical, |
| 58 | +} from '@payloadcms/richtext-lexical/client' |
| 59 | +import React, { useState } from 'react' |
| 60 | + |
| 61 | +import { lexicalFullyFeaturedSlug } from '../../slugs.js' |
| 62 | + |
| 63 | +export const Component: JSONFieldClientComponent = (args) => { |
| 64 | + // Manually manage the editor state |
| 65 | + const [value, setValue] = useState<DefaultTypedEditorState | undefined>(() => |
| 66 | + buildEditorState({ text: 'state default' }), |
| 67 | + ) |
| 68 | + |
| 69 | + const handleReset = React.useCallback(() => { |
| 70 | + setValue(buildEditorState({ text: 'state default' })) |
| 71 | + }, []) |
| 72 | + |
| 73 | + return ( |
| 74 | + <div> |
| 75 | + <RenderLexical |
| 76 | + field={{ name: 'myField' }} |
| 77 | + initialValue={buildEditorState({ text: 'default value' })} |
| 78 | + schemaPath={`collection.${lexicalFullyFeaturedSlug}.richText`} |
| 79 | + setValue={setValue as any} |
| 80 | + value={value} |
| 81 | + /> |
| 82 | + <button onClick={handleReset} style={{ marginTop: 8 }} type="button"> |
| 83 | + Reset Editor State |
| 84 | + </button> |
| 85 | + </div> |
| 86 | + ) |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +## Choosing the schemaPath |
| 91 | + |
| 92 | +`schemaPath` tells the server which richText field to render. This gives the server the exact nested field schemas (blocks, relationship drawers, upload fields, tables, etc.). |
| 93 | + |
| 94 | +Format: |
| 95 | + |
| 96 | +- `collection.<collectionSlug>.<fieldPath>` |
| 97 | +- `global.<globalSlug>.<fieldPath>` |
| 98 | + |
| 99 | +Example (top level): `collection.posts.richText` |
| 100 | + |
| 101 | +Example (nested in a group/tab): `collection.posts.content.richText` |
| 102 | + |
| 103 | +<Banner type="info"> |
| 104 | + **Tip:** If your target editor lives deep in arrays/blocks and you're unsure of the exact path, you can define a **hidden top-level richText** purely as a "render anchor": |
| 105 | + |
| 106 | +```ts |
| 107 | +{ |
| 108 | + name: 'onDemandAnchor', |
| 109 | + type: 'richText', |
| 110 | + admin: { hidden: true } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +Then use `schemaPath="collection.posts.onDemandAnchor"` |
| 115 | + |
| 116 | +</Banner> |
0 commit comments