Button block
An inline button with a token variant, icons, a link and a visually hidden title option.
On this page
The Button block is an inline call to action: a token-variant button with optional icons before and after the title, and the shared link fields.
Where it is offeredLink to this section
Offered in every tier: root, region, fragment and slot, as an inline block that sits inside a line of text.
FieldsLink to this section
| Field | Type | Label | Default | Notes |
|---|---|---|---|---|
_tier | select | Options: root (Root), region (Region), fragment (Fragment), slot (Slot), stack (Stack) | ||
alignSelf | radio | Align Self | center | Shown when siblingData?._tier==="stack"; Required; Shown when siblingData?.setSelfAlign; Options: start (Start), center (Center), end (End), stretch (Stretch) |
flex1 | checkbox | Flex 1 | false | Shown when siblingData?._tier==="stack" |
grow | checkbox | Grow | false | Shown when siblingData?._tier==="stack" |
hideTitle | checkbox | Hide title visually | false | Shown when Boolean(siblingData?.title) |
iconAfter | text | Icon after the title | async()=>{const raw=typeof defaultValue==="function"?defaultValue():defaultValue;if(!raw||typeof raw!=="string")return void 0;return resolveDefaultIdentifier(raw)} | |
iconBefore | text | Icon before the title | async()=>{const raw=typeof defaultValue==="function"?defaultValue():defaultValue;if(!raw||typeof raw!=="string")return void 0;return resolveDefaultIdentifier(raw)} | |
linkType | radio | Link Type | custom | Required; Options: custom (Custom URL), internal (Internal Link) |
message | ui | Shown when siblingData?._tier==="stack" | ||
newTab | checkbox | Open in new tab | false | |
reference | relationship | Choose a page to link to | Required; Shown when the custom field-helper condition passes; Related to pages | |
setSelfAlign | checkbox | Define Self Alignment | false | Shown when siblingData?._tier==="stack" |
shrink | checkbox | Shrink | false | Shown when siblingData?._tier==="stack" |
title | text | Button title | ||
url | text | Enter a URL | `` | Required; Shown when the custom field-helper condition passes |
variant | radio | Variant | primary | Required; Options: primary (Primary), secondary (Secondary) |
The block's fields are exported as ButtonBlockFields for reuse; see Reusing block fields. Default icons for new buttons come from the button plugin option; see button and chip defaults.
Hide title visually (Advanced Settings) keeps the title in the DOM for screen readers while hiding it visually (sr-only), so an icon-only button still has an accessible name.
Rendered outputLink to this section
Renders the Button component as Button.a; the resolved link supplies its href.
ConverterLink to this section
buttonConverter always renders <Button.a>. It resolves custom URLs and localized page references, including the configured homepage, and adds icon markup through resolveIconHtml. New-tab links get rel="noopener noreferrer" and a screen-reader cue. hideTitle applies sr-only! to ButtonTitle.
CustomizingLink to this section
Import ButtonBlock from @systhemaui/payload/blocks as the starting schema for a project block. Register the definition and your renderer through customBlocks, using type: 'inline' and the editor tiers you intend to support. A distinct slug creates a new block; a converter registered under the existing button 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.