Simple text
Field-level catalog tables below stay in English — they match the machine design schema used by the editor, API, and MCP.
Decoration and visibility use Decoration & visibility (BlockShell).
Single-style text (plain or heading). Omit
levelfor a paragraph; set h1–h6 only when you need semantic heading hierarchy. Multiline is fine. For mixed rich formatting, use RichTextBlock. Font size is one px number (typography.size/fontSize) — there is no supported mobile/desktop font-size map and no HeadingBlock line-height. Do not inventtypography.sizeByBreakpointortypography.lineHeight; they are ignored at render. Shellshell.box.sizeByBreakpointsizes the box, not the type. For line-height use RichTextBlock.
Examples
Plain label
{
"content": {
"text": "Browse categories"
},
"typography": {
"size": 18,
"weight": 500
}
}Section heading
{
"content": {
"text": "Latest threads"
},
"level": "h2",
"typography": {
"size": 28
}
}Fields
content
text
Plain text content. Newlines are preserved; the whole string shares one style. Mix in {{icon:iconId}} chips the same way as ButtonBlock; the icon picker appends a chip at the end. An older icon prop still renders, and is folded into a leading chip when the block is edited.
content: {
text: "Browse {{icon:arrow-right}}"
}level
Optional semantic heading level. When omitted, the block renders as a paragraph (<p>).
Leave unset for ordinary body/label text. Set h1–h6 only when the text is a document heading. Prefer one H1 per page topic; use H2/H3 for sections. A clear heading hierarchy helps visitors, screen readers, search engines, and AI agents.
Options: h1, h2, h3, h4, h5, h6
level: "h2"icon
Legacy leading icon id. Prefer {{icon:…}} chips in text. Still rendered when no icon chip is present.
icon: "arrow-right"decorationSize
Editor-only control — does not persist its own value.
Editor control for decoration width, thickness, and spacing. Does not persist its own value.
// Writes:
decorationWidth: 96
decorationThickness: 8
decorationSpacing: 12textShadowSize
Editor-only control — does not persist its own value.
Editor control for shadow offset and blur. Does not persist its own value.
// Writes:
textShadowOffsetX: 3
textShadowOffsetY: 3
textShadowBlur: 0typography
textAlign
Horizontal text alignment. On a heading, an explicit left is stored and pulls the block to the start of a centered flex parent. Omitting it keeps the parent alignment.
Options: left, center, right
textAlign: "center"fontSize
Unit: px
Font size in pixels as a single JSON number (stored as typography.size). Not responsive: there is no typography.sizeByBreakpoint or per-breakpoint font size on HeadingBlock, and no HeadingBlock lineHeight.
fontSize: 48fontWeight
Numeric font weight (CSS font-weight).
fontWeight: 600fontFamily
Font family. A theme token (theme-heading, theme-body, theme-mono), a rich-text font id, a CSS generic family (sans-serif, serif, monospace, system-ui, ui-sans-serif, cursive, fantasy), or a comma-separated stack.
fontFamily: "theme-heading"italic
When true, renders the text in italic style.
typography: {
italic: false
}underline
Underline.
appearance
color
text
textColorLight
Text color used in light theme.
textColorLight: "#111827"textColorDark
Text color used in dark theme.
textColorDark: "#f9fafb"decoration
decorationEnabled
Toggles an underline or accent decoration under the text.
decorationEnabled: truedecorationWidth
Unit: px
Width of the text decoration line in pixels.
appearance: {
decoration: {
decorationWidth: 96
}
}decorationThickness
Unit: px
Stroke thickness of the text decoration in pixels.
appearance: {
decoration: {
decorationThickness: 8
}
}decorationSpacing
Unit: px
Gap between the text and its decoration in pixels.
appearance: {
decoration: {
decorationSpacing: 12
}
}decorationColorLight
Decoration color in light theme.
appearance: {
decoration: {
decorationColorLight: "#2563eb"
}
}decorationColorDark
Decoration color in dark theme.
appearance: {
decoration: {
decorationColorDark: "#60a5fa"
}
}underlineMode
Underline rendering mode for decorated text. inline | separate (option catalog underline-mode).
Options: inline, separate
appearance: {
decoration: {
underlineMode: "inline" | "separate"
}
}textShadow
textShadowEnabled
Enables a drop shadow behind the text.
textShadowEnabled: falsetextShadowOffsetX
Unit: px
Horizontal offset of the text shadow in pixels.
appearance: {
textShadow: {
textShadowOffsetX: 3
}
}textShadowOffsetY
Unit: px
Vertical offset of the text shadow in pixels.
appearance: {
textShadow: {
textShadowOffsetY: 3
}
}textShadowBlur
Unit: px
Blur radius of the text shadow in pixels.
appearance: {
textShadow: {
textShadowBlur: 0
}
}textShadowColorLight
Text shadow color in light theme.
appearance: {
textShadow: {
textShadowColorLight: "rgba(0, 0, 0, 0.55)"
}
}textShadowColorDark
Text shadow color in dark theme.
appearance: {
textShadow: {
textShadowColorDark: "rgba(0, 0, 0, 0.75)"
}
}<details><summary>Default props</summary>
{
"shell": {
"visibility": {
"authVisibility": "all",
"routeLockVisibility": "all",
"roleVisibility": [],
"entryActionVisibility": "all",
"queryPageVisibility": "all",
"hideWhenEmpty": ""
},
"anchor": {
"anchorId": "",
"anchorKey": ""
},
"spacing": {
"padding": {
"value": "none",
"enabled": false
},
"margin": {
"enabled": false
}
},
"box": {
"enabled": false
},
"background": {
"enabled": false,
"width": "page",
"kind": "solid",
"solid": {
"color": {
"light": "",
"dark": ""
}
},
"gradient": {
"angle": 180,
"type": "linear",
"colors": [
{
"light": "",
"dark": "",
"offset": 50
},
{
"light": "",
"dark": "",
"offset": 50
}
],
"color1Light": "",
"color1Dark": "",
"color2Light": "",
"color2Dark": ""
},
"image": {
"src": "",
"mode": "cover",
"repeatSize": 100,
"position": "center"
},
"motion": {
"enabled": false,
"directionDeg": 0,
"speed": 20,
"rotateDegPerSec": 0,
"animationMode": "particle"
},
"video": {
"src": "",
"source": "file",
"youtubeUrl": "",
"fit": "cover",
"loop": true,
"repeatSize": 100
},
"particles": {
"shape": "circle",
"svgSrc": "",
"colorMode": "solid",
"colorLight": "#ffffff88",
"colorDark": "#ffffff66",
"size": 12,
"jitter": 0.2,
"count": 40,
"lifetimeSec": 4,
"speed": 40,
"animType": "fade",
"fromSide": "left",
"toSide": "right"
},
"grid": {
"style": "cells",
"motionDirectionDeg": 0,
"motionSpeed": 0,
"rotateDegPerSec": 0,
"hoverGrowLimitPct": 50,
"hoverRotateLimitDeg": 0,
"reactionTimeSec": 1,
"hoverGrow": true,
"hoverRotate": false,
"hoverColor": false,
"hoverColorLight": "#ffffff55",
"hoverColorDark": "#ffffff33",
"reactionSpeed": 1
},
"backdrop": {
"enabled": false,
"blurPx": 0,
"brightness": 1,
"contrast": 1,
"saturate": 1,
"grayscale": 0,
"sepia": 0,
"hueRotateDeg": 0
}
},
"pointerEvents": "auto",
"effects": {
"enabled": false,
"opacity": 1,
"blurPx": 0,
"brightness": 1,
"contrast": 1,
"saturate": 1,
"grayscale": 0,
"sepia": 0,
"hueRotateDeg": 0,
"dropShadowOffsetX": 0,
"dropShadowOffsetY": 0,
"dropShadowBlur": 0,
"dropShadowColorLight": "",
"dropShadowColorDark": "",
"mixBlendMode": "normal"
},
"animation": {
"scroll": {
"enabled": false,
"type": "fadeIn",
"duration": 600,
"delay": 0
},
"tilt": {
"enabled": false,
"intensity": 12
},
"wander": {
"enabled": false,
"speed": 40,
"jitter": 40,
"turnRadius": 50,
"turnSmoothness": 40,
"limits": "parent"
},
"transform": {
"enabled": false,
"rotateX": 0,
"rotateY": 0,
"rotateZ": 0,
"translateX": 0,
"translateY": 0,
"translateZ": 0,
"scale": 1
}
}
},
"appearance": {
"border": {
"enabled": false,
"style": "solid",
"colorLight": "",
"colorDark": ""
},
"shadow": {
"enabled": false,
"valueLight": "",
"valueDark": ""
},
"color": {
"text": {
"light": "",
"dark": ""
}
},
"decoration": {
"enabled": false,
"decorationWidth": 96,
"decorationThickness": 8,
"decorationSpacing": 12,
"decorationColorLight": "",
"decorationColorDark": "",
"underlineMode": "inline"
},
"textShadow": {
"enabled": false,
"textShadowOffsetX": 3,
"textShadowOffsetY": 3,
"textShadowBlur": 0,
"textShadowColorLight": "rgba(0, 0, 0, 0.55)",
"textShadowColorDark": "rgba(0, 0, 0, 0.7)"
}
},
"icon": "none",
"typography": {
"align": "left",
"size": 48,
"weight": 600,
"family": "theme-heading",
"italic": false,
"underline": false
}
}</details>