Unreleased

Block catalog

Every built-in block, the editor tiers that offer it and how to register blocks.

On this page

Built-in blocks define the Payload fields editors fill in and the converters that turn stored Lexical nodes into frontend components. The tables below show default placement; block toggles and module options can remove entries.

The Stack item picker with block thumbnails

Blocks by tierLink to this section

Which tier offers a block by default. A tier is the kind of rich-text editor a field uses; see Editor tiers.

Block	`root`	`region`	`fragment`	`slot`
Section	✅	❌	❌	❌
Columns	✅	⚠️	❌	❌
Stack and Nested Stack	✅	✅	✅	❌
Feature	✅	❌	❌	❌
Gallery	✅	❌	❌	❌
Carousel	✅	✅	❌	❌
Rich Text	Stack item	Stack item	Stack item	❌
Accordion	✅	✅	❌	❌
Card	✅	⚠️	❌	❌
Quote	✅	✅	✅	❌
Form ‡	✅	✅	✅	❌
Posts †	✅	❌	❌	❌
Component	✅	❌	❌	❌
Image	✅	✅	✅	❌
Video	✅	✅	✅	❌
YouTube	✅	✅	✅	❌
Embed	✅	✅	✅	❌
Google Maps	✅	✅	✅	❌
Hero blocks	register	register	register	register
Button	✅	✅	✅	✅
Chip	✅	✅	✅	✅
Icon	✅	✅	✅	✅
Avatar	✅	✅	✅	✅

⚠️ = needs the withColumns / withCard option of regionLexicalEditor. † = only with the Posts module. ‡ = only with the Forms module. "register" = offered by no editor until you add it through customBlocks.

Layout blocksLink to this section

SectionBlock, ColumnsBlock, StackBlock, NestedStackBlock, FeatureBlock, GalleryBlock, CarouselBlock.

Content blocksLink to this section

RichTextBlock, AccordionBlock, QuoteBlock, CardBlock, EmbedBlock, GoogleMapsBlock.

With the Posts module on, PostsBlock joins them; see Posts block.

Media blocksLink to this section

ImageBlock, VideoBlock, YoutubeBlock, plus EmbedBlock and GoogleMapsBlock.

Inline blocksLink to this section

ButtonBlock, ButtonBlockFields (reusable field array), ChipBlock, IconBlock, AvatarBlock.

Hero blocksLink to this section

HeroSimpleBlock, HeroBackgroundBlock and HeroFeatureBlock are offered by no editor until you register them; see Hero blocks.

Registering blocksLink to this section

Register a project block with a Payload definition, a converter and an explicit editor tier. editor accepts one tier or an array; omitting it offers the block in every tier, including slot. type: 'inline' places it within text; type: 'block' places it between paragraphs.

src/payload/blocks/ProjectQuote.tsx

import type { CustomBlockConverter } from '@systhemaui/payload'
import { QuoteBlock } from '@systhemaui/payload/blocks'
import { Quote } from '@systhemaui/next'

export const ProjectQuoteBlock = { ...QuoteBlock, slug: 'projectQuote', interfaceName: 'ProjectQuote' }

export const projectQuoteConverter: CustomBlockConverter = ({ node, nodesToJSX }) => {
  const fields = node.fields as { content?: { root?: { children?: unknown[] } } }
  const children = fields.content?.root?.children
  return <Quote.blockquote>{children ? nodesToJSX({ nodes: children }) : null}</Quote.blockquote>
}

src/payload.config.ts

import { withSysthema } from '@systhemaui/payload'
import { ProjectQuoteBlock, projectQuoteConverter } from './payload/blocks/ProjectQuote'

const config = withSysthema(payloadConfig, {
  customBlocks: [
    {
      type: 'block',
      data: ProjectQuoteBlock,
      editor: ['root', 'region', 'fragment'],
      converter: projectQuoteConverter,
    },
  ],
})

payloadConfig is your project's existing Payload configuration. Import block definitions from @systhemaui/payload/blocks; copy the definition before changing fields or its slug. Do not mutate the shared export.

Overriding a converterLink to this section

Custom converters merge after the built-in converter map. Registering a converter with a definition whose slug is quote replaces the quote renderer, while a distinct slug such as projectQuote adds a separate block. The map is split into block and inline-block converters, so keep type consistent with the built-in block. Nested text must go through nodesToJSX to retain headings, links and inline blocks. Relationship-based blocks require populated documents, not IDs.

A custom converter used in client-mode live preview must also be registered through livePreview.clientSetup; see Client mode. Adding a field changes the schema, so regenerate your Payload types and use your project's migration process before deployment.

For full examples, see Custom blocks. Every block also carries an icon and a picker thumbnail; see Block images.