Columns block
A responsive column layout whose items can be plain, row or card columns.
On this page
The Columns block lays content out in responsive columns. Each item holds its own fragment editor, and an item can render as a card.
Where it is offeredLink to this section
Offered in the root tier, and in the region tier when the editor enables withColumns (the Section, Feature and Gallery bodies do). Each column's content uses the fragment editor. A block used inside a Columns item 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) | ||
alignX | radio | Horizontal Alignment | left | Required; Options: left (Left), center (Center), right (Right), justify (Justify) |
alignY | radio | Vertical Alignment | stretch | Required; Options: stretch (Stretch), top (Top), center (Center), bottom (Bottom) |
columnCount | number | Number of columns in one row | 2 | Required |
disableAnimation | checkbox | Disable Wrapper Animations | false | |
disableStagger | checkbox | Disable Stagger Animation | false | Shown when !siblingData?.disableAnimation |
divideX | checkbox | Horizontal Divider | ||
divideY | checkbox | Vertical Divider | ||
gapX | number | Horizontal Gap | 3 | Required |
gapY | number | Vertical Gap | 6 | Required |
items.cardVariant | radio | Card Variant | default | Required; Shown when siblingData?.layout=="card"; Options: default (Default), highlighted (Highlighted) |
items.columnSpan | number | Column Span | 1 | Required; Shown when siblingData?.layout=="column"||siblingData?.layout=="card" |
items.content | richText | Content | ||
items.layout | radio | Layout | column | Required; Options: column (Column), card (Card), row (Row) |
items.linkType | radio | Link Type | none | Required; Shown when the custom field-helper condition passes; Options: none (None), custom (Custom URL), internal (Internal Link) |
items.newTab | checkbox | Open in new tab | false | Shown when the custom field-helper condition passes |
items.reference | relationship | Choose a page to link to | Required; Shown when the custom field-helper condition passes; Related to pages | |
items.sticky | checkbox | Sticky | false | Shown when siblingData?.layout=="column"||siblingData?.layout=="card" |
items.url | text | Enter a URL | `` | Required; Shown when the custom field-helper condition passes |
items | array | Items | ||
layoutBg | radio | Background Variant | main | Required; Shown when siblingData?._tier==="root"; Options: main (Main), alternative (Alternative) |
padding | number | Padding | 2 | Required; Shown when siblingData?._tier==="root" |
theme | radio | Color | default | Required; Shown when siblingData?._tier==="root"; Options: default (Default), dark (Dark) |
Card columnsLink to this section
A columns item with layout: 'card' behaves like a Card: media placed directly in it can span the card width; see Media inside a card. Columns items take the shared link fields, so a card column can link; see Link fields.
Rendered outputLink to this section
Renders the Columns component, with column count, gaps, alignment and dividers from the block fields.
ConverterLink to this section
columnsConverter converts each item body with nodesToJSX. layout chooses Column, Card or Row; a Row spans the configured column count. Card links use the shared localized reference resolver. Gap slider indices map to token gap names. At root tier the converter adds a Section with theme, background and padding; inside a region it renders bare Columns.
CustomizingLink to this section
Import ColumnsBlock 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 columns 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.