HeadingBlock: Heading

text

The string value of the heading.

text: "My Heading"

level

Semantic heading level for the rendered element.

The semantic heading level describes the hierarchy and structure of the content on a page. It is generally recommended that each page have one primary H1 heading, with H2, H3, and subsequent headings used to organize subsections logically. Using multiple H1 headings is generally not recommended when they represent multiple unrelated page topics.

A clear heading hierarchy benefits visitors, screen-reader users, search-engine crawlers, and AI agents by making the page structure easier to understand and navigate.

level: "h2"

icon

The icon displayed to the left of the heading.

icon: "none"

textAlign

Horizontal text alignment.

textAlign: "center"

fontFamily

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

fontFamily: "theme-heading"

fontSizepx

Font size in pixels.

fontSize: 48

fontWeight

Numeric font weight (CSS font-weight).

fontWeight: 600

italic

When true, renders the text in italic style.

italic: false

underlineMode

Underline rendering mode for decorated text.

underlineMode: "inline"

textColorLight

Text color used in light theme.

textColorLight: "#111827"

textColorDark

Text color used in dark theme.

textColorDark: "#f9fafb"

decorationEnabled

Toggles an underline or accent decoration under the text.

decorationEnabled: true

decorationSizeeditor only

Editor control for decoration width, thickness, and spacing. Does not persist its own value.

// Writes:
decorationWidth: 96
decorationThickness: 8
decorationSpacing: 12

decorationWidthpx

Width of the text decoration line in pixels.

decorationWidth: 96

decorationThicknesspx

Stroke thickness of the text decoration in pixels.

decorationThickness: 8

decorationSpacingpx

Gap between the text and its decoration in pixels.

decorationSpacing: 12

decorationColorLight

Decoration color in light theme.

decorationColorLight: "#2563eb"

decorationColorDark

Decoration color in dark theme.

decorationColorDark: "#60a5fa"

textShadowEnabled

Enables a drop shadow behind the text.

textShadowEnabled: false

textShadowSizeeditor only

Editor control for shadow offset and blur. Does not persist its own value.

// Writes:
textShadowOffsetX: 3
textShadowOffsetY: 3
textShadowBlur: 0

textShadowOffsetXpx

Horizontal offset of the text shadow in pixels.

textShadowOffsetX: 3

textShadowOffsetYpx

Vertical offset of the text shadow in pixels.

textShadowOffsetY: 3

textShadowBlurpx

Blur radius of the text shadow in pixels.

textShadowBlur: 0

textShadowColorLight

Text shadow color in light theme.

textShadowColorLight: "rgba(0, 0, 0, 0.55)"

textShadowColorDark

Text shadow color in dark theme.

textShadowColorDark: "rgba(0, 0, 0, 0.75)"

showOnBreakpoints

Per-breakpoint visibility. Set a breakpoint to `false` to hide the block on that viewport. Missing keys default to visible.

showOnBreakpoints: { mobile: false }

showOnLocales

Limit which website locales show the block. Empty / missing means all enabled locales. Set a locale to `false` to hide.

showOnLocales: { tr: false }

authVisibility

Who can see the block based on website sign-in state.

authVisibility: "authenticated"

routeLockVisibility

On locked object routes, show always, only when unlocked, or only when locked.

routeLockVisibility: "all"

roleVisibility

Optional list of website user role labels. Empty means all roles. Matching is case-sensitive.

roleVisibility: ["moderator"]

entryActionVisibility

Object-component only: show when the current entry exposes matching actions.

entryActionVisibility: "all"

queryPageVisibility

Optional: limit list blocks to the first query page only.

queryPageVisibility: "all"

customizeEnabled

Enables the decoration controls below in the editor.

customizeEnabled: true

paddingEnabled

Turns padding controls on for this block.

paddingEnabled: true

paddingtoken

Theme spacing token applied as padding. Tokens let site owners customize spacing while blocks continue to share a consistent design language.

padding: "md"

paddingByBreakpointtoken

Theme spacing token per breakpoint. Use this when the block needs different, but still theme-consistent, spacing at different viewport sizes.

paddingByBreakpoint: { desktop: "md", mobile: "sm" }

marginsEnabled

Turns margin controls on (configured via size/position maps).

marginsEnabled: false

sizeByBreakpoint

Optional width/height constraints per breakpoint. Modes: `fillParent` (stretch), `fitContent` (intrinsic), `static` (fixed length via `widthStatic`/`heightStatic` + unit), `ratio` (percent of the other axis via `widthRatio`/`heightRatio`).

`static` uses `widthStaticUnit` / `heightStaticUnit`: `px`, `vw`, `vh`, `vmin`, or `vmax` (default `px`). Example full-page background: `widthStatic: 100`, `widthStaticUnit: "vw"`, `heightStatic: 100`, `heightStaticUnit: "vh"` with fixed positioning and `pointerEvents: "none"`. `ratio` values are percentages of the opposite axis. `fillParent` and `fitContent` take no numeric unit.

sizeByBreakpoint: {
  desktop: {
    widthMode: "static",
    widthStatic: 100,
    widthStaticUnit: "vw",
    heightMode: "static",
    heightStatic: 100,
    heightStaticUnit: "vh"
  }
}

overflow

CSS overflow on the decoration frame.

overflow: "hidden"

pointerEvents

Whether the decoration frame receives pointer events. Use `none` for full-page decorative backgrounds so clicks pass through.

pointerEvents: "auto"

positionEnabled

Enables absolute/relative positioning overlays.

positionEnabled: false

positionByBreakpoint

Positioning overlays per breakpoint (`static`, `relative`, `absolute`, `fixed`, `sticky`) with optional offsets in pixels (`top`, `right`, `bottom`, `left`).

positionByBreakpoint: {
  desktop: { position: "relative", top: 0, left: 0 }
}

backgroundEnabled

Enables background fill, gradient, or image.

backgroundEnabled: true

backgroundWidth

Background span: page column or full viewport bleed.

backgroundWidth: "page"

backgroundKind

Solid color, gradient, image, muted autoplay video, or canvas animation (particles / reactive grid).

backgroundKind: "solid"

backgroundColorLight

Solid background color in light theme.

backgroundColorLight: "#ffffff"

backgroundColorDark

Solid background color in dark theme.

backgroundColorDark: "#111827"

gradientAngledeg

Gradient angle in degrees when `backgroundKind` is `gradient`.

gradientAngle: 135

gradientColors

Gradient stops with light/dark theme pairs.

gradientColors: [
  { light: "#2563eb", dark: "#1e3a8a" },
  { light: "#93c5fd", dark: "#1e40af" }
]

backgroundImageSrc

Background image source when `backgroundKind` is `image`.

backgroundImageSrc: "https://cdn.example/bg.jpg"

backgroundImageMode

How the background image is sized.

backgroundImageMode: "cover"

backgroundRepeatSizepx

Tile size in pixels when background image mode is `repeat`.

backgroundRepeatSize: 64

backgroundPosition

CSS background-position value.

backgroundPosition: "center"

backgroundMotionEnabled

Seamless pan (and optional rotate) for gradient and image backgrounds.

backgroundMotionEnabled: true

backgroundMotionDirectionDegdeg

Pan direction in degrees (0 = right).

backgroundMotionDirectionDeg: 0

backgroundMotionSpeed

Relative pan speed for seamless cycling.

backgroundMotionSpeed: 20

backgroundMotionRotateDegPerSecdeg

Continuous rotation speed in degrees per second (0 = off).

backgroundMotionRotateDegPerSec: 0

backgroundVideoSrc

Video URL when `backgroundKind` is `video`. Always muted, autoplay, plays inline; never captures focus.

backgroundVideoSrc: "https://cdn.example/bg.mp4"

backgroundVideoFit

`cover` / `fill` use object-fit; `repeat` tiles frames on canvas.

Options: cover, fill, repeat

backgroundVideoFit: "cover"

backgroundVideoLoop

Loop the background video (default true).

backgroundVideoLoop: true

backgroundAnimationMode

Particle field or reactive grid (filled cells or continuous outlines) when `backgroundKind` is `animation`.

Options: particle, reactiveGrid

backgroundAnimationMode: "particle"

backgroundAnimShape

Built-in shape or custom SVG for particles/grid cells.

Options: circle, square, roundedSquare, triangle, diamond, hexagon, star, cross, svg

backgroundAnimShape: "circle"

backgroundAnimSvgSrc

SVG URL when shape is `svg`.

backgroundAnimSvgSrc: "https://cdn.example/shape.svg"

backgroundAnimColorMode

`solid` tints shapes; `fromAsset` keeps SVG colors.

Options: solid, fromAsset

backgroundAnimColorMode: "solid"

backgroundAnimSizepx

Base particle or cell size in pixels.

backgroundAnimSize: 12

backgroundAnimJitter

Particle-only 0–1 randomization for count, size, lifetime, and speed.

backgroundAnimJitter: 0.2

backgroundGridStyle

Reactive grid rendering: filled `cells`, or `continuous` shape outlines tiled edge-to-edge into one connected lattice that ripples around the cursor. Ignored for `svg` shapes, which always render as cells.

backgroundGridStyle: "cells"

backgroundGridHoverGrowLimitPct%

Maximum cell size change at the pointer. Positive values grow cells; negative values shrink them. A value of `50` reaches 150% scale after the configured reaction time.

backgroundGridHoverGrowLimitPct: 50

backgroundGridHoverRotateLimitDegdeg

Maximum cell rotation at the pointer. Positive values rotate clockwise; negative values rotate counterclockwise.

backgroundGridHoverRotateLimitDeg: 0

backgroundGridReactionTimeSecs

Seconds for cells or the continuous-grid ripple to reach their configured hover limit, and to return after the pointer leaves.

backgroundGridReactionTimeSec: 1

borderEnabled

Enables border color, style, width, and radius.

borderEnabled: false

borderColorLight

Border color in light theme.

borderColorLight: "#e5e7eb"

borderColorDark

Border color in dark theme.

borderColorDark: "#374151"

borderStyle

CSS border style.

borderStyle: "solid"

borderWidthtoken

Border width token.

borderWidth: "sm"

borderRadiustoken

Border radius token.

borderRadius: "md"

shadowEnabled

Enables box shadow values for light/dark themes.

shadowEnabled: false

shadowValueLight

CSS box-shadow value in light theme.

shadowValueLight: "0 8px 24px rgba(0, 0, 0, 0.12)"

shadowValueDark

CSS box-shadow value in dark theme.

shadowValueDark: "0 8px 24px rgba(0, 0, 0, 0.45)"

scrollAnimationEnabled

Enables enter-on-scroll animation.

scrollAnimationEnabled: false

scrollAnimationType

Enter-on-scroll animation preset.

scrollAnimationType: "fadeIn"

scrollAnimationDurationms

Animation duration in milliseconds.

scrollAnimationDuration: 600

scrollAnimationDelayms

Animation delay in milliseconds.

scrollAnimationDelay: 0

cursorTiltEnabled

Tilts the block slightly toward the pointer.

cursorTiltEnabled: false

cursorTiltIntensity

Strength of the cursor tilt effect.

cursorTiltIntensity: 8

transformEnabled

Enables CSS transform controls.

transformEnabled: false

transformRotateXdeg

Rotation around the X axis in degrees.

transformRotateX: 0

transformRotateYdeg

Rotation around the Y axis in degrees.

transformRotateY: 0

transformRotateZdeg

Rotation around the Z axis in degrees.

transformRotateZ: 0

transformTranslateXpx

Horizontal translation in pixels.

transformTranslateX: 0

transformTranslateYpx

Vertical translation in pixels.

transformTranslateY: 0

transformTranslateZpx

Depth translation in pixels.

transformTranslateZ: 0

transformScaleratio

Uniform scale factor (unitless).

transformScale: 1

transformPerspectivepx

CSS perspective distance in pixels.

transformPerspective: 800

decorationBySelector

Advanced: apply decoration token overlays for `hover`, `active`, and `focus`. Missing overlay keys inherit the default flat props.

decorationBySelector: {
  hover: { backgroundColorLight: "#f3f4f6" }
}

clipboardeditor only

Editor-only copy/paste helpers for block props.

// Editor-only — does not persist a stored value