Card block
A token-variant card with a fragment editor body that can link as a whole.
On this page
The Card block is a card with a fragment editor body. It takes the shared link fields, so the whole card can be a link.
Where it is offeredLink to this section
Offered in the root tier, and in the region tier when the editor enables withCard (the Section, Feature and Gallery bodies do). Its body uses the fragment editor; a block used inside a card must target 'fragment'.
FieldsLink to this section
| Field | Type | Label | Default | Notes |
|---|---|---|---|---|
_tier | select | Options: root (Root), region (Region), fragment (Fragment), slot (Slot), stack (Stack) | ||
content | richText | Content | ||
linkType | radio | Link Type | none | Required; Options: none (None), custom (Custom URL), internal (Internal Link) |
newTab | checkbox | Open in new tab | false | Shown when the custom field-helper condition passes |
reference | relationship | Choose a page to link to | Required; Shown when the custom field-helper condition passes; Related to pages | |
theme | radio | Color | inherit | Required; Options: inherit (Auto), default (Default), dark (Dark) |
url | text | Enter a URL | `` | Required; Shown when the custom field-helper condition passes |
variant | radio | Variant | default | Required; Options: default (Default), highlighted (Highlighted) |
width | radio | Width alignment | default | Required; Shown when (hasValue?hasValue(siblingData):true)&&siblingData?._tier!=="fragment"; Options: default (Default), container (Container) |
Media inside a cardLink to this section
When a figure-rendering media block — ImageBlock, VideoBlock, YoutubeBlock, and also the GoogleMapsBlock and EmbedBlock (see Content blocks) — is a direct child of a card (a card block, or a columns item with layout: 'card'), a Width alignment: Default / Card width radio (cardWidth) appears (the standard container/screen breakouts are hidden in this context). Selecting "Card width" wraps the media in <Figure width="card"> so it spans the full inner width of the card and sits flush to its edges (the card's overflow: hidden + border-radius clip it to the rounded corners). The control is hidden everywhere else — at root, in plain/row columns, in accordions, and for media nested inside a stack within a card (only a direct card child can break out correctly). This is driven by a server-injected _inCard flag (injectTierIntoLexicalRoot), since _tier alone can't distinguish a card from other fragment-tier contexts.
Accessible nameLink to this section
A card that resolves to a link takes its accessible name from its visible content, not from the block name; see Block name → ID/ARIA.
Rendered outputLink to this section
Renders the Card component as Card, or as Card.a when linkType is custom or internal.
ConverterLink to this section
cardConverter converts content.root.children with nodesToJSX. linkType selects <Card.a> or a plain Card. Outside fragment tier it adds a <Figure> for width alignment; at fragment tier it leaves the Card in the parent track. theme: 'inherit' becomes an omitted theme prop.
CustomizingLink to this section
Import CardBlock from @systhemaui/payload/blocks as the starting schema for a project block. Register the definition and your renderer through customBlocks, using type: 'block' and the editor tiers you intend to support. A distinct slug creates a new block; a converter registered under the existing card slug takes precedence over the built-in converter. Keep the fields that renderer reads, including populated relationships and nested editor states.
See Registering blocks for the configuration pattern and Converters for the renderer contract. A project converter used in client-mode live preview also needs browser registration.