Skip to content

Style definition schema

Every key a style definition can use, in one reference table.

Overview

Every key below is valid in both a hook_canvas_builder_styles() return value and a *.canvas_builder_styles.yml file — it's the same schema either way. Keys marked "leaf/tab only" are only meaningful inside a children or tabs entry, not at a definition's top level. See Extending for how these are used.

Key Type Notes
enabled bool Gates whether the definition is ever built. Defaults to FALSE if omitted: a definition with no enabled: true is silently inert.
type string, required Dispatches to a StyleInterface::getType() handler. Built in: select, media, group. Extend with your own via Custom style types (e.g. motion, or the toggle example there).
label string Falls back to ucfirst($id) in several UI paths if omitted, so set it explicitly.
description string Optional help text shown under the label.
form_group string Which prop-group tab (see Prop groups & widgets) the definition renders under, typically style or advanced.
weight int Sort order. Canvas Builder's own groups reserve -100..-10.
icon string Key into \Drupal\canvas_builder\Icons.
open bool Whether an accordion group starts expanded.
libraries string | list\<string> Asset libraries attached whenever this definition (or an enabled leaf under it) is active; see Custom style types §3. YAML overlays union this list rather than replacing it.
children array\<string, array> (group type only) Id-keyed map of sub-fields rendered as a stacked accordion (e.g. spacing.children.padding).
tabs array\<string, array> (group type only) Id-keyed map of sub-fields rendered as a tab switcher (e.g. background.tabs.color/image/video).
style string (leaf/tab only) Picks the sub-handler a group's GroupStyle dispatches a leaf to. Only two values do anything: box_model under children, and media under tabs; anything else falls through to a select. Distinct from the top-level type key, which only a group definition itself uses.
settings_key string (leaf/tab only) Config key (in canvas_builder.settings) holding this leaf's option rows, resolved via CanvasBuilderManager::getConfiguredResponsiveOptions().
settings_label string (leaf/tab only) Overrides the settings-form field label derived from settings_key; does not affect the editor-facing label.
bundles_config_key string (leaf/tab only, media/overlay) Config key holding the allowed media-bundle list, resolved via getConfiguredBundles().
default_bundles list\<string> (leaf/tab only) Fallback bundles when bundles_config_key is unset/empty; defaults to ['image'] if omitted entirely. A YAML overlay replaces this list wholesale, never index-merges.
media_bundles list\<string> (leaf/tab only) Inline, non-admin-configurable bundle list.
overlay bool (tab only, media) Exposes a color/opacity/blend overlay sub-control on a media tab, gated by an auto-derived toggle key {plugin}_{tab}_overlay.
swatch bool (leaf/tab only, select) Renders the options as a color-swatch picker instead of a dropdown/radio list.
swatch_type string (leaf/tab only, select) Swatch rendering mode, e.g. background, text.
icon_group string (leaf/tab only, select) Icon set used for the option list, e.g. align.
admin_note string (HTML) (leaf/tab only) Optional caveat appended to the settings-form table caption for this option table.
admin_note_if_class string (leaf/tab only) Makes admin_note conditional: it only shows if a configured option row's class contains this token.
viewport_scoped bool (leaf/tab only, select) Renders exactly one resolved class per breakpoint instead of the union every other key gets, for options that are mutually-exclusive variants, not self-scoping framework classes.
options — Reserved/opaque; always wholesale-replaced by a YAML overlay regardless of shape. Not otherwise consumed anywhere in this module today.
Two related-but-distinct concepts, easy to confuse with the above

kind is not a schema key. It never appears in a *.canvas_builder_styles.yml file or a hook's return value. It's a runtime render-element property ('#canvas_style' => ['kind' => 'class'|'media', 'key' => ...]) a StyleInterface::build() implementation stamps onto form elements so StyleManager::persistElement() knows how to persist them; see Custom style types §2.

layout_maps is not the same mechanism. canvas_builder.settings:layout_maps looks similarly named but is unrelated: it's a config value inside a framework profile snapshot, managed by FrameworkProfileManager and loaded from fixed-path files under src/Service/ProfileData/ that canvas_builder alone owns. There is no {provider}.layout_maps.yml (or similar) discovery convention for other modules/themes to hook into.