astro-payload-richtext-lexical

JHB Software - Astro Payload RichText Lexical Renderer

Renders Payload CMS Lexical rich text content to Astro elements.

Installation

pnpm add @jhb.software/astro-payload-richtext-lexical

Usage

---
import RichTextLexical from '@jhb.software/astro-payload-richtext-lexical/RichTextLexical.astro'
import CustomUpload from '../components/CustomUpload.astro'
import CustomBlock from '../components/CustomBlock.astro'

// content is the Lexical JSON from Payload CMS
const { content } = Astro.props
---

<RichTextLexical
  nodes={content.root.children}
  UploadRenderer={CustomUpload}
  BlockRenderer={CustomBlock}
/>

Props

Prop	Type	Required	Description
nodes	LexicalNode[]	Yes	The array of Lexical nodes from content.root.children
class	string	No	CSS class to apply to the wrapper div
UploadRenderer	AstroComponentFactory	No	Custom component to render upload nodes
BlockRenderer	AstroComponentFactory	No	Custom component to render block and inline block nodes
slugifyHeadingId	SlugifyHeadingId | false	No	Custom function for heading IDs, or false to disable
resolveInternalLink	ResolveInternalLink	No	Custom function to resolve internal link hrefs

Usage with Tailwind CSS Typography

The component outputs semantic HTML without any styling. You can use Tailwind CSS Typography (@tailwindcss/typography) to style the content by adding the prose class to the wrapper div.

<RichTextLexical
  nodes={content.root.children}
  class="prose"
  UploadRenderer={CustomUpload}
  BlockRenderer={CustomBlock}
/>

Custom Renderers

UploadRenderer

The UploadRenderer component receives:

type Props = {
  node: UploadNode
}

interface UploadNode {
  type: 'upload'
  relationTo: string
  value: {
    id: string | number
    url: string
    width: number
    height: number
    filename: string
    [key: string]: unknown
  }
}

BlockRenderer

The BlockRenderer component receives:

type Props = {
  node: BlockNode | InlineBlockNode
  inline: boolean // true for inline blocks, false for regular blocks
}

interface BlockNode {
  type: 'block'
  fields: {
    id: string
    blockName: string
    blockType: string
    [key: string]: unknown
  }
}

Configuration Options

slugifyHeadingId

By default, h2 and h3 headings automatically get an id attribute generated from their text content (useful for anchor links and table of contents).

<!-- Default behavior: h2/h3 get auto-generated IDs -->
<RichTextLexical nodes={content.root.children} />

<!-- Disable heading IDs entirely -->
<RichTextLexical nodes={content.root.children} slugifyHeadingId={false} />

<!-- Custom slugify function -->
<RichTextLexical
  nodes={content.root.children}
  slugifyHeadingId={(text, tag) => {
    // Generate IDs for all headings, not just h2/h3
    return text.toLowerCase().replace(/\s+/g, '-')
  }}
/>

The function signature:

type SlugifyHeadingId = (text: string, tag: string) => string | undefined

resolveInternalLink

Internal links in Payload CMS reference documents by their ID. By default, the renderer uses the path field from the populated document (works with @jhb.software/payload-pages-plugin).

For custom URL structures, provide your own resolver:

---
import RichTextLexical from '@jhb.software/astro-payload-richtext-lexical/RichTextLexical.astro'
import type { ResolveInternalLink } from '@jhb.software/astro-payload-richtext-lexical'

const resolveInternalLink: ResolveInternalLink = (doc, relationTo) => {
  // Use path field if available
  if ('path' in doc && typeof doc.path === 'string') {
    return doc.path
  }
  // Fallback to slug for blog posts
  if ('slug' in doc && typeof doc.slug === 'string') {
    if (relationTo === 'posts') {
      return `/blog/${doc.slug}`
    }
    return `/${doc.slug}`
  }
  return undefined
}
---

<RichTextLexical nodes={content.root.children} resolveInternalLink={resolveInternalLink} />

The function signature:

type ResolveInternalLink = (doc: Record<string, unknown>, relationTo: string) => string | undefined

Supported Node Types

• heading (h1-h6)
• paragraph
• text (with formatting: bold, italic, underline, strikethrough, code, subscript, superscript)
• link / autolink
• list (ordered and unordered)
• listitem
• quote (blockquote)
• table
• upload (requires UploadRenderer)
• block / inlineBlock (requires BlockRenderer)
• horizontalrule
• linebreak

Types

You can import types for use in your custom renderers and configuration:

import type {
  LexicalNode,
  HeadingNode,
  ParagraphNode,
  TextNode,
  LinkNode,
  ListNode,
  UploadNode,
  BlockNode,
  InlineBlockNode,
  SlugifyHeadingId,
  ResolveInternalLink,
} from '@jhb.software/astro-payload-richtext-lexical'

Contributing

We welcome contributions! Please open an issue to report bugs or suggest improvements, or submit a pull request with your changes.