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 level for a paragraph; set h1–h6 only when you need semantic heading hierarchy. Multiline is fine. For mixed rich formatting, use RichTextBlock.

Examples

Plain label

{
  "text": "Browse categories",
  "typography": {
    "fontSize": 18,
    "fontWeight": 500
  }
}

Section heading

{
  "text": "Latest threads",
  "level": "h2",
  "typography": {
    "fontSize": 28
  }
}

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.

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.

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: 12

`textShadowSize`

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: 0

`typography`

`textAlign`

Horizontal text alignment.

typography: {
  textAlign: "center"
}

`fontSize`

Unit: px

Font size in pixels.

typography: {
  fontSize: 48
}

`fontWeight`

Numeric font weight (CSS font-weight).

typography: {
  fontWeight: 600
}

`fontFamily`

Font family id. Theme tokens (theme-heading, theme-body, theme-mono) or a rich-text font id.

typography: {
  fontFamily: "theme-heading"
}

`italic`

When true, renders the text in italic style.

typography: {
  italic: false
}

`color`

`textColorLight`

Text color used in light theme.

color: {
  textColorLight: "#111827"
}

`textColorDark`

Text color used in dark theme.

color: {
  textColorDark: "#f9fafb"
}

`decoration`

`decorationEnabled`

Toggles an underline or accent decoration under the text.

decoration: {
  decorationEnabled: true
}

`decorationWidth`

Unit: px

Width of the text decoration line in pixels.

decoration: {
  decorationWidth: 96
}

`decorationThickness`

Unit: px

Stroke thickness of the text decoration in pixels.

decoration: {
  decorationThickness: 8
}

`decorationSpacing`

Unit: px

Gap between the text and its decoration in pixels.

decoration: {
  decorationSpacing: 12
}

`decorationColorLight`

Decoration color in light theme.

decoration: {
  decorationColorLight: "#2563eb"
}

`decorationColorDark`

Decoration color in dark theme.

decoration: {
  decorationColorDark: "#60a5fa"
}

`underlineMode`

Underline rendering mode for decorated text.

decoration: {
  underlineMode: "inline"
}

`textShadow`

`textShadowEnabled`

Enables a drop shadow behind the text.

textShadow: {
  textShadowEnabled: false
}

`textShadowOffsetX`

Unit: px

Horizontal offset of the text shadow in pixels.

textShadow: {
  textShadowOffsetX: 3
}

`textShadowOffsetY`

Unit: px

Vertical offset of the text shadow in pixels.

textShadow: {
  textShadowOffsetY: 3
}

`textShadowBlur`

Unit: px

Blur radius of the text shadow in pixels.

textShadow: {
  textShadowBlur: 0
}

`textShadowColorLight`

Text shadow color in light theme.

textShadow: {
  textShadowColorLight: "rgba(0, 0, 0, 0.55)"
}

`textShadowColorDark`

Text shadow color in dark theme.

textShadow: {
  textShadowColorDark: "rgba(0, 0, 0, 0.75)"
}

Default props

{
  "icon": "none",
  "typography": {
    "textAlign": "left",
    "fontSize": 48,
    "fontWeight": 600,
    "fontFamily": "theme-heading",
    "italic": false
  },
  "color": {
    "textColorLight": "",
    "textColorDark": ""
  },
  "decoration": {
    "decorationEnabled": false,
    "decorationWidth": 96,
    "decorationThickness": 8,
    "decorationSpacing": 12,
    "decorationColorLight": "",
    "decorationColorDark": "",
    "underlineMode": "inline"
  },
  "textShadow": {
    "textShadowEnabled": false,
    "textShadowOffsetX": 3,
    "textShadowOffsetY": 3,
    "textShadowBlur": 0,
    "textShadowColorLight": "rgba(0, 0, 0, 0.55)",
    "textShadowColorDark": "rgba(0, 0, 0, 0.7)"
  },
  "shell": {
    "customizeEnabled": false,
    "pointerEvents": "auto",
    "decorationBySelector": {},
    "visibility": {
      "showOnBreakpoints": {},
      "showOnLocales": {},
      "authVisibility": "all",
      "routeLockVisibility": "all",
      "roleVisibility": [],
      "entryActionVisibility": "all",
      "queryPageVisibility": "all",
      "hideWhenEmpty": ""
    },
    "anchor": {
      "anchorId": "",
      "anchorKey": ""
    },
    "box": {
      "padding": "none",
      "paddingEnabled": false,
      "marginsEnabled": false,
      "sizeByBreakpoint": {},
      "positionEnabled": false,
      "positionByBreakpoint": {}
    },
    "background": {
      "backgroundEnabled": false,
      "backgroundWidth": "page",
      "backgroundKind": "solid",
      "backgroundColorLight": "",
      "backgroundColorDark": "",
      "gradientType": "linear",
      "gradientAngle": 180,
      "gradientColors": [
        {
          "light": "",
          "dark": "",
          "offset": 50
        },
        {
          "light": "",
          "dark": "",
          "offset": 50
        }
      ],
      "gradientColor1Light": "",
      "gradientColor1Dark": "",
      "gradientColor2Light": "",
      "gradientColor2Dark": "",
      "backgroundImageSrc": "",
      "backgroundImageMode": "cover",
      "backgroundRepeatSize": 100,
      "backgroundPosition": "center",
      "backgroundMotionEnabled": false,
      "backgroundMotionDirectionDeg": 0,
      "backgroundMotionSpeed": 20,
      "backgroundMotionRotateDegPerSec": 0,
      "backgroundVideoSrc": "",
      "backgroundVideoFit": "cover",
      "backgroundVideoLoop": true,
      "backgroundVideoRepeatSize": 100,
      "backgroundAnimationMode": "particle",
      "backgroundAnimShape": "circle",
      "backgroundAnimSvgSrc": "",
      "backgroundAnimColorMode": "solid",
      "backgroundAnimColorLight": "#ffffff88",
      "backgroundAnimColorDark": "#ffffff66",
      "backgroundAnimSize": 12,
      "backgroundAnimJitter": 0.2,
      "backgroundParticleCount": 40,
      "backgroundParticleLifetimeSec": 4,
      "backgroundParticleSpeed": 40,
      "backgroundParticleAnimType": "fade",
      "backgroundParticleFromSide": "left",
      "backgroundParticleToSide": "right",
      "backgroundGridStyle": "cells",
      "backgroundGridMotionDirectionDeg": 0,
      "backgroundGridMotionSpeed": 0,
      "backgroundGridRotateDegPerSec": 0,
      "backgroundGridHoverGrowLimitPct": 50,
      "backgroundGridHoverRotateLimitDeg": 0,
      "backgroundGridReactionTimeSec": 1,
      "backgroundGridHoverGrow": true,
      "backgroundGridHoverRotate": false,
      "backgroundGridHoverColor": false,
      "backgroundGridHoverColorLight": "#ffffff55",
      "backgroundGridHoverColorDark": "#ffffff33",
      "backgroundGridReactionSpeed": 1,
      "backgroundBackdropEnabled": false,
      "backgroundBackdropBlurPx": 0,
      "backgroundBackdropBrightness": 1,
      "backgroundBackdropContrast": 1,
      "backgroundBackdropSaturate": 1,
      "backgroundBackdropGrayscale": 0,
      "backgroundBackdropSepia": 0,
      "backgroundBackdropHueRotateDeg": 0
    },
    "border": {
      "borderEnabled": false,
      "borderColorLight": "",
      "borderColorDark": "",
      "borderStyle": "solid"
    },
    "shadow": {
      "shadowEnabled": false,
      "shadowValueLight": "",
      "shadowValueDark": ""
    },
    "effects": {
      "effectsEnabled": false,
      "opacity": 1,
      "filterBlurPx": 0,
      "filterBrightness": 1,
      "filterContrast": 1,
      "filterSaturate": 1,
      "filterGrayscale": 0,
      "filterSepia": 0,
      "filterHueRotateDeg": 0,
      "filterDropShadowOffsetX": 0,
      "filterDropShadowOffsetY": 0,
      "filterDropShadowBlur": 0,
      "filterDropShadowColorLight": "",
      "filterDropShadowColorDark": "",
      "mixBlendMode": "normal"
    },
    "scrollAnimation": {
      "scrollAnimationEnabled": false,
      "scrollAnimationType": "fadeIn",
      "scrollAnimationDuration": 600,
      "scrollAnimationDelay": 0
    },
    "cursorTilt": {
      "cursorTiltEnabled": false,
      "cursorTiltIntensity": 12
    },
    "wander": {
      "wanderEnabled": false,
      "wanderSpeed": 40,
      "wanderJitter": 40,
      "wanderTurnRadius": 50,
      "wanderTurnSmoothness": 40,
      "wanderLimits": "parent"
    },
    "transform": {
      "transformEnabled": false,
      "transformRotateX": 0,
      "transformRotateY": 0,
      "transformRotateZ": 0,
      "transformTranslateX": 0,
      "transformTranslateY": 0,
      "transformTranslateZ": 0,
      "transformScale": 1
    }
  }
}

Simple text

Examples

Fields

`text`

`level`

`icon`

`decorationSize`

`textShadowSize`

`typography`

`textAlign`

`fontSize`

`fontWeight`

`fontFamily`

`italic`

`color`

`textColorLight`

`textColorDark`

`decoration`

`decorationEnabled`

`decorationWidth`

`decorationThickness`

`decorationSpacing`

`decorationColorLight`

`decorationColorDark`

`underlineMode`

`textShadow`

`textShadowEnabled`

`textShadowOffsetX`

`textShadowOffsetY`

`textShadowBlur`

`textShadowColorLight`

`textShadowColorDark`