Dekorasyon ve görünürlük (BlockShell)

Aşağıdaki alan düzeyi katalog tabloları İngilizce kalır — düzenleyici, API ve MCP’nin kullandığı makine tasarım şemasıyla birebir uyumludur.

Most blocks share one reusable shell object. It is stored on shell, not as separate block types. The field menu matches that object: shell.visibility, shell.anchor, shell.box, shell.background, shell.border, shell.shadow, shell.effects, and the motion groups (scrollAnimation, cursorTilt, wander, transform). customizeEnabled, pointerEvents, and decorationBySelector sit directly on shell. Visibility controls who and where the block appears. The other groups are the Customize controls: spacing, background, border, shadow, effects, and motion. Flat shell keys still load. The next save writes them under shell.

Aşağıdaki alan düzeyi katalog tabloları İngilizce kalır — düzenleyici, API ve MCP’nin kullandığı makine tasarım şemasıyla birebir uyumludur.

Alanlar

`shell`

`visibility`

`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.

Options: all, authenticated, anonymous

shell: {
  visibility: {
    authVisibility: "authenticated"
  }
}

`routeLockVisibility`

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

Options: all, when_unlocked, when_locked

shell: {
  visibility: {
    routeLockVisibility: "all"
  }
}

`roleVisibility`

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

shell: {
  visibility: {
    roleVisibility: ["moderator"]
  }
}

`entryActionVisibility`

Show when the current entry exposes matching actions.

Options: all, canUpdate, canDelete

shell: {
  visibility: {
    entryActionVisibility: "all"
  }
}

`queryPageVisibility`

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

Options: all, first_page_only

shell: {
  visibility: {
    queryPageVisibility: "all"
  }
}

`variableVisibility`

Hide the block unless a document variable matches. op is eq, neq, gt, lt, gte, lte, in, or not-empty. Numeric comparison is used when both sides parse as numbers. in checks membership in a comma-separated list or an array. not-empty is true when the variable is not blank; if value is item.<field> or {{var:item.<field>}}, it checks that field instead. Inside VariableArrayTemplateBlock the right-hand side may be item.<field>. An empty variableId leaves the block visible. Stored at shell.visibility.variableVisibility.

shell: {
  visibility: {
    variableVisibility: { variableId: "size", op: "eq", value: "item.size" }
  }
}

`hideWhenEmpty`

Hides the block when its content is empty. Stored at shell.visibility.hideWhenEmpty.

shell: {
  visibility: {
    hideWhenEmpty: true
  }
}

`anchor`

`anchorId`

DOM id for in-page links. Stored at shell.anchor.anchorId. Summary lists shell when this object is present.

shell: {
  anchor: {
    anchorId: "pricing"
  }
}

`anchorKey`

Stable key used to derive the anchor id. Stored at shell.anchor.anchorKey.

shell: {
  anchor: {
    anchorKey: "pricing"
  }
}

`customizeEnabled`

Turns the decoration controls on. Until it is true, shell.box (including sizeByBreakpoint), spacing, background, border, shadow, effects and motion are ignored when the block renders — they are stored but have no effect. get_design_warnings reports design.warning.box_size_ignored_without_customize for that state.

shell: {
  customizeEnabled: true
}

`spacing`

`padding`

Unit: token

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

Options: none, xs, sm, md, lg, xl

padding: "md"

`paddingEnabled`

Padding is always on. Stored false is read as 0 on every side and saved back as true with the padding values cleared.

paddingEnabled: true

`paddingByBreakpoint`

Unit: token

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

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

`paddingInsetsByBreakpoint`

Padding Insets By Breakpoint.

`margin`

`marginsEnabled`

Margins are always on. Stored false is read as 0 on every side and saved back as true with the margin values cleared.

marginsEnabled: true

`marginInsetsByBreakpoint`

Margin Insets By Breakpoint.

`box`

`sizeByBreakpoint`

Optional width/height constraints keyed by website layout breakpoint id (from get_theme section=layout / Layout editor: mobile, desktop, or breakpoint-N). Exact id match only — desktop does not alias to breakpoint-1024. Modes: fillParent (stretch), fitContent (intrinsic), static (fixed length via widthStatic/heightStatic + unit), relative (percent of parent via widthRelative/heightRelative), viewport (percent of the browser window via widthViewport/heightViewport, breaks out of the page column), ratio (percent of the other axis via widthRatio/heightRatio).

Keys are layout breakpoint ids, not viewport nicknames. After custom breakpoints are added, the open large range may be breakpoint-1024 (or similar)—set that id, not desktop. 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". Prefer viewport over static+vw when the block should span the window from inside a narrower page column. ratio values are percentages of the opposite axis. fillParent and fitContent take no numeric unit.

shell: {
  box: {
    sizeByBreakpoint: {
      "breakpoint-1024": {
        widthMode: "static",
        widthStatic: 720,
        widthStaticUnit: "px",
        heightMode: "fitContent"
      }
    }
  }
}

`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).

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

`overflow`

CSS overflow on the decoration frame.

Options: visible, hidden, auto, clip

shell: {
  box: {
    overflow: "hidden"
  }
}

`background`

`backgroundEnabled`

Enables background fill, gradient, or image.

backgroundEnabled: true

`backgroundWidth`

Background span: page column or full viewport bleed.

Options: page, full

backgroundWidth: "page"

`backgroundKind`

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

Options: solid, gradient, image, video, animation

backgroundKind: "solid"

`solid.color`

`backgroundColorLight`

Solid background color in light theme.

backgroundColorLight: "#ffffff"

`backgroundColorDark`

Solid background color in dark theme.

backgroundColorDark: "#111827"

`gradient`

`gradientType`

Linear, radial, or conic gradient when backgroundKind is gradient.

Options: linear, radial, conic

gradientType: "linear"

`gradientAngle`

Unit: deg

Linear gradient direction or conic start angle in degrees when backgroundKind is gradient.

gradientAngle: 135

`gradientMirrorRtl`

When true and the active website locale is right-to-left, linear and conic gradient angles use (360 − angle) mod 360. Off by default, so existing gradients stay the same. Radial gradients are unchanged.

gradientMirrorRtl: true

`gradientColors`

Gradient stops with light/dark pairs and segment offsets (CSS % is the running sum).

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

`gradientColor1Light`

Gradient Color1 Light.

`gradientColor1Dark`

Gradient Color1 Dark.

`gradientColor2Light`

Gradient Color2 Light.

`gradientColor2Dark`

Gradient Color2 Dark.

`backgroundClipPath`

Optional CSS clip-path on the decoration background layer. Empty means no clip. The content is not clipped. Values that contain ;, {, }, or < are ignored.

shell: {
  background: {
    backgroundClipPath: "inset(0 round 24px)"
  }
}

`image`

`backgroundImageSrc`

Background image source when backgroundKind is image.

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

`backgroundImageAlt`

Background Image Alt.

`backgroundImageDecorative`

Background Image Decorative.

`backgroundImageCredit`

Background Image Credit.

`backgroundImageMode`

How the background image is sized.

Options: cover, contain, repeat

backgroundImageMode: "cover"

`backgroundImageSizes`

Background Image Sizes.

`backgroundImageSlotShare`

Background Image Slot Share.

`backgroundRepeatSize`

Unit: px

Tile size in pixels when background image mode is repeat.

backgroundRepeatSize: 64

`backgroundPosition`

CSS background-position value.

backgroundPosition: "center"

`motion`

`backgroundMotionEnabled`

Seamless pan (and optional rotate) for image backgrounds.

backgroundMotionEnabled: true

`backgroundMotionDirectionDeg`

Unit: deg

Pan direction in degrees (0 = right).

backgroundMotionDirectionDeg: 0

`backgroundMotionSpeed`

Relative pan speed for seamless cycling.

backgroundMotionSpeed: 20

`backgroundMotionRotateDegPerSec`

Unit: deg

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

backgroundMotionRotateDegPerSec: 0

`backgroundAnimationMode`

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

Options: particle, reactiveGrid

backgroundAnimationMode: "particle"

`video`

`backgroundVideoSrc`

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

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

`backgroundVideoSource`

file uses an uploaded video. youtube plays a muted covering embed from backgroundVideoYoutubeUrl.

Options: file, youtube

backgroundVideoSource: "file"

`backgroundVideoYoutubeUrl`

YouTube link or 11-character id when backgroundVideoSource is youtube. Empty or invalid renders nothing.

backgroundVideoYoutubeUrl: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

`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

`backgroundVideoRepeatSize`

Background Video Repeat Size.

`particles`

`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"

`backgroundAnimColorLight`

Background Anim Color Light.

`backgroundAnimColorDark`

Background Anim Color Dark.

`backgroundAnimSize`

Unit: px

Base particle or cell size in pixels.

backgroundAnimSize: 12

`backgroundAnimJitter`

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

backgroundAnimJitter: 0.2

`backgroundParticleCount`

Background Particle Count.

`backgroundParticleLifetimeSec`

Background Particle Lifetime Sec.

`backgroundParticleSpeed`

Background Particle Speed.

`backgroundParticleAnimType`

Background Particle Anim Type.

`backgroundParticleFromSide`

Background Particle From Side.

`backgroundParticleToSide`

Background Particle To Side.

`grid`

`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.

Options: cells, continuous

backgroundGridStyle: "cells"

`backgroundGridMotionDirectionDeg`

Background Grid Motion Direction Deg.

`backgroundGridMotionSpeed`

Background Grid Motion Speed.

`backgroundGridRotateDegPerSec`

Background Grid Rotate Deg Per Sec.

`backgroundGridHoverGrowLimitPct`

Unit: %

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

`backgroundGridHoverRotateLimitDeg`

Unit: deg

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

backgroundGridHoverRotateLimitDeg: 0

`backgroundGridReactionTimeSec`

Unit: s

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

backgroundGridReactionTimeSec: 1

`backgroundGridHoverGrow`

Background Grid Hover Grow.

`backgroundGridHoverRotate`

Background Grid Hover Rotate.

`backgroundGridHoverColor`

Background Grid Hover Color.

`backgroundGridHoverColorLight`

Background Grid Hover Color Light.

`backgroundGridHoverColorDark`

Background Grid Hover Color Dark.

`backgroundGridReactionSpeed`

Background Grid Reaction Speed.

`backdrop`

`backgroundBackdropEnabled`

Background Backdrop Enabled.

`backgroundBackdropBlurPx`

Background Backdrop Blur Px.

`backgroundBackdropBrightness`

Background Backdrop Brightness.

`backgroundBackdropContrast`

Background Backdrop Contrast.

`backgroundBackdropSaturate`

Background Backdrop Saturate.

`backgroundBackdropGrayscale`

Background Backdrop Grayscale.

`backgroundBackdropSepia`

Background Backdrop Sepia.

`backgroundBackdropHueRotateDeg`

Background Backdrop Hue Rotate Deg.

`effects`

`effectsEnabled`

Effects Enabled.

`opacity`

Opacity.

`filterBlurPx`

Filter Blur Px.

`filterBrightness`

Filter Brightness.

`filterContrast`

Filter Contrast.

`filterSaturate`

Filter Saturate.

`filterGrayscale`

Filter Grayscale.

`filterSepia`

Filter Sepia.

`filterHueRotateDeg`

Filter Hue Rotate Deg.

`filterDropShadowOffsetX`

Filter Drop Shadow Offset X.

`filterDropShadowOffsetY`

Filter Drop Shadow Offset Y.

`filterDropShadowBlur`

Filter Drop Shadow Blur.

`filterDropShadowColorLight`

Filter Drop Shadow Color Light.

`filterDropShadowColorDark`

Filter Drop Shadow Color Dark.

`mixBlendMode`

Mix Blend Mode.

`animation`

`scroll`

`scrollAnimationEnabled`

Enables enter-on-scroll animation.

scrollAnimationEnabled: false

`scrollAnimationType`

Enter-on-scroll animation preset.

Options: fadeIn, slideInBottom, slideInTop, slideInLeft, slideInRight, zoomIn, zoomOut, rotateIn, rotateOut, bounceIn, bounceOut, pulse

scrollAnimationType: "fadeIn"

`scrollAnimationDuration`

Unit: ms

Animation duration in milliseconds.

scrollAnimationDuration: 600

`scrollAnimationDelay`

Unit: ms

Animation delay in milliseconds.

scrollAnimationDelay: 0

`scrollAnimationStart`

Scroll Animation Start.

`scrollAnimationTiming`

Scroll Animation Timing.

`tilt`

`cursorTiltEnabled`

Tilts the block slightly toward the pointer.

cursorTiltEnabled: false

`cursorTiltIntensity`

Strength of the cursor tilt effect.

cursorTiltIntensity: 8

`wander`

`wanderEnabled`

Moves the block continuously inside its parent with bouncing limits.

wanderEnabled: false

`wanderSpeed`

0–100 scaler for wander velocity.

wanderSpeed: 40

`wanderJitter`

0–100; low biases longer segment durations.

wanderJitter: 40

`wanderTurnRadius`

0–100; low keeps headings closer to the previous.

wanderTurnRadius: 50

`wanderTurnSmoothness`

0–100; how softly headings blend between segments.

wanderTurnSmoothness: 40

`wanderLimits`

Bounce against the parent box or the document viewport.

wanderLimits: "parent" | "document"

`transform`

`transformEnabled`

Enables CSS transform controls.

transformEnabled: false

`transformRotateX`

Unit: deg

Rotation around the X axis in degrees.

transformRotateX: 0

`transformRotateY`

Unit: deg

Rotation around the Y axis in degrees.

transformRotateY: 0

`transformRotateZ`

Unit: deg

Rotation around the Z axis in degrees.

transformRotateZ: 0

`transformTranslateX`

Unit: px

Horizontal translation in pixels.

transformTranslateX: 0

`transformTranslateY`

Unit: px

Vertical translation in pixels.

transformTranslateY: 0

`transformTranslateZ`

Unit: px

Depth translation in pixels.

transformTranslateZ: 0

`transformScale`

Unit: ratio

Uniform scale factor (unitless).

transformScale: 1

`transformPerspective`

Unit: px

CSS perspective distance in pixels.

transformPerspective: 800

`pointerEvents`

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

Options: auto, none

shell: {
  pointerEvents: "auto"
}

`decorationBySelector`

Advanced: apply decoration token overlays for hover, active, focus, and selected. active is the pressed state. selected matches [data-selected] and [aria-checked=true]. Missing overlay keys inherit the other decoration values.

shell: {
  decorationBySelector: {
    hover: { backgroundColorLight: "#f3f4f6" },
    selected: { backgroundColorLight: "#111827" }
  }
}

`appearance`

`border`

`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.

Options: solid, dashed, dotted

borderStyle: "solid"

`borderWidth`

Unit: token

Border width token.

Options: none, sm, md, lg

borderWidth: "sm"

`borderWidthByBreakpoint`

Border Width By Breakpoint.

`borderRadius`

Unit: token

Border radius token.

Options: none, sm, md, lg, xl, full

borderRadius: "md"

`shadow`

`shadowEnabled`

Enables box shadow values for light and dark themes. When enabled and both values are empty, the theme shadow.md is used: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1).

shadowEnabled: false

`shadowValueLight`

CSS box-shadow value in light theme. Empty uses theme shadow.md.

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

`shadowValueDark`

CSS box-shadow value in dark theme. Empty uses theme shadow.md.

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

`clipboard`

Editor-only control — does not persist its own value.

Editor-only copy/paste helpers for block props.

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

Örnekler

Hide on mobile

{
  "shell": {
    "visibility": {
      "showOnBreakpoints": {
        "mobile": false
      }
    }
  }
}

Signed-in only + light padding

{
  "shell": {
    "visibility": {
      "authVisibility": "authenticated"
    },
    "customizeEnabled": true,
    "box": {
      "paddingEnabled": true,
      "padding": "md"
    }
  }
}