Every field type

One of every gcb-lite control rendered server-side. Edit any field via the Inspector or click directly on a value below — the Inspector opens at the matching control. The “Raw” toggle on each row shows the stored JSON.

Text

text Text text_field
Single-line text input.
Docs

The simplest controls. Single-line input (`text`) or multi-line (`textarea`). Both store a single string.

Stored: string

Supports

  • Plain string values, no formatting
  • Validation rules (required, minLength, maxLength, pattern)
  • Placeholder text and inline help

Config options

default string
Initial value if the author hasn't edited the field.
placeholder string
Greyed-out hint shown when the input is empty.
helpText string
One-line description shown below the input.
validation.required boolean
Block save until the field is filled in.
validation.minLength number
Minimum character count.
validation.maxLength number
Maximum character count. Shown as "X / Y" counter in the editor.
validation.pattern string (regex)
Regex the value must match. Enforced client- and server-side.
Raw value
"Single-line text input."
textarea Textarea textarea_field
Multi-line text input. Wraps onto two paragraphs when the renderer splits on \n\n.
Raw value
"Multi-line text input.\nWraps onto two paragraphs when the renderer splits on \\n\\n."
email Email email_field
hello@example.com
Docs

Single-line input with `type="email"` so mobile keyboards show the @-key and browsers do basic validation. Stores a plain string.

Stored: string

Supports

  • HTML5 email keyboard / browser validation via `type="email"`
  • Default placeholder of "name@example.com" if none provided

Config options

placeholder string default: "name@example.com"
Greyed-out hint shown when the input is empty.
helpText string
One-line description shown below the input.

Gotchas

  • Browser-level validation is light. For stricter checks pair with `validation.pattern` or sanitise server-side with `sanitize_email()`.
Raw value
"hello@example.com"
url URL url_field
Docs

URL picker with a custom display label and an "open in new tab" toggle. Stores all three together as a single object.

Stored: { url: string, text: string, opensInNewTab: boolean }

Supports

  • URL, display text, and target=_blank toggle in one field
  • Default values via `default: { url, text, opensInNewTab }`

Config options

default object
Initial value, e.g. `{ "url": "", "text": "Learn more", "opensInNewTab": false }`.

Gotchas

  • When `opensInNewTab` is true, always emit both `target="_blank"` AND `rel="noopener noreferrer"` to prevent reverse-tabnabbing.
Raw value
{
    "url": "https://gutenbergcontrolblocks.com",
    "text": "Visit GCB",
    "opensInNewTab": true
}
code Code code_field
console.log('hello world');
Docs

Monospace textarea for code snippets. Same stored shape as `textarea` (plain string) but rendered with a fixed-width font for readability.

Stored: string

Supports

  • Plain string values, no syntax highlighting
  • Configurable height via `rows`

Config options

rows number default: "8"
Height of the textarea, in rows.
placeholder string
Greyed-out hint shown when the input is empty.
helpText string
One-line description shown below the input.

Gotchas

  • No syntax highlighting or auto-indent — a future version may swap in CodeMirror, but for now it's a styled textarea.
  • Server-side: never echo the value as HTML without escaping. For executable snippets you control, render inside `<pre><code>` after `esc_html()`.
Raw value
"console.log('hello world');"

Choice

select Select select_field
medium
Docs

Dropdown single-select. Supports plain options, legacy `map` configs, and `tokenGroup` binding to theme.json tokens.

Stored: string for plain options OR a full token object (`{ key, slug, value, cssVar }`) when bound to a `tokenGroup`

Supports

  • Plain `{ value, label }` option lists
  • Legacy `map` configs (key/value pairs that map keys to richer values)
  • `tokenGroup` binding — options come from a theme.json token group
  • Optional `tokenKeys` filter to narrow a token group to specific keys
  • Auto-prepended placeholder option when no `defaultOptionKey` is set

Config options

options { value, label }[]
The choices for plain-list mode.
map object | array
Legacy form. Key/value pairs mapping option keys to richer values.
tokenGroup string
Bind to a theme.json token group (e.g. `"color"`, `"font-size"`). Stored value becomes the full token object.
tokenKeys string[]
When `tokenGroup` is set, restrict to these token keys only.
defaultOptionKey string
Initial value if the field is empty.
placeholder string
Label for the auto-prepended empty option.

Gotchas

  • Stored shape depends on config: plain options store the string value, `tokenGroup` stores `{ key, slug, value, cssVar }`. Branch on type when reading.
  • For multi-select use `checkbox-group` (vertical) or `button-group` (horizontal).
Raw value
"medium"
radio Radio radio_field
center
Docs

Single-select shown as a vertical list of radio buttons. Stores the chosen option's `value` as a string.

Stored: string — the selected option `value`

Supports

  • Single-select from a fixed list of options
  • Coerces option values to strings — pick from `toggle-group` if you need a compact segmented look

Config options

options { value, label }[]
The choices. Required.
default string
Pre-selected value. Should match one of the option `value`s.

Gotchas

  • Option values are stringified before storage — `{ value: 1 }` becomes `"1"`. Compare with `String()` on the read side.
  • For multi-select use `checkbox-group`. For a compact horizontal segmented control use `toggle-group`.
Raw value
"center"
checkbox Checkbox checkbox_field
true
Docs

Multi-select control. Alias `button-group` renders the same control with different visual styling. Use when authors need to pick zero or more options from a fixed list.

Stored: array of strings — the selected option `value`s

Supports

  • Multi-select from a fixed list of options
  • Two visual styles via the alias `button-group` (same stored shape)
  • Default selection via `default` array

Config options

options { value, label }[]
The choices. Required.
default string[]
Pre-selected values. Empty array if omitted.

Gotchas

  • For single-select use `toggle-group`. The controls are picked by the SHAPE of the saved value: array of strings (multi) vs single string (single).
Raw value
true
checkbox-group Checkbox group checkbox_group_field
reactnext
Raw value
[
    "react",
    "next"
]
toggle Toggle toggle_field
true
Docs

Two related controls. `toggle` is an on/off switch storing a boolean. `toggle-group` is a single-select segmented control storing the chosen `value` as a string.

Stored: boolean (`toggle`) or string (`toggle-group`)

Supports

  • Simple on/off boolean via `toggle`
  • Single-select segmented control via `toggle-group`
  • Pairs naturally with `conditionalLogic` to gate other fields

Config options

options { value, label }[]
`toggle-group` only. The choices shown as segments. Required for `toggle-group`.
default boolean or string
For `toggle` a boolean; for `toggle-group` the pre-selected `value` (should match one of the options or no segment will be active).

Gotchas

  • For multi-select use `checkbox-group` (alias: `button-group`). The two are picked by the SHAPE of the saved value, not by visual style.
Raw value
true
toggle-group Toggle group toggle_group_field
published
Raw value
"published"
button-group Button group (multi) button_group_field
hf
Docs

Multi-select shown as a row of pressable buttons. Same stored shape as `checkbox-group` — only the visual affordance differs (buttons-in-a-row vs checkboxes-in-a-column).

Stored: array of strings — the selected option `value`s

Supports

  • Multi-select from a fixed list of options
  • Horizontal, compact visual style
  • Default selection via `default` array

Config options

options { value, label }[]
The choices. Required.
default string[]
Pre-selected values. Empty array if omitted.

Gotchas

  • Not single-select. For a segmented single-choice control use `toggle-group` — `button-group` stores an ARRAY of values.
Raw value
[
    "h",
    "f"
]

Numeric

number Number number_field
42
Docs

Numeric input with up/down spinners. Stores a number (not a string), with optional min, max, step and decimals (the precision it prints with).

Stored: number

Supports

  • Min / max bounds and step increments
  • Coerces empty input to `0` so consumers always see a number

Config options

min number
Minimum allowed value.
max number
Maximum allowed value.
step number default: "1"
Increment for the spinner / arrow keys.
decimals integer
The precision the field prints with, as a count of decimals read off the sample in the design ("5.0" is 1, "4.95" is 2, "14,395" is 0). The render passes it to gcblite_number(); without it a value prints with the decimals it was stored with, and a default stored as a number prints "5", not "5.0".
placeholder string
Greyed-out hint shown when the input is empty.

Gotchas

  • Empty input becomes `0`, not `null` or empty string. If you need "unset" semantics, pair with a boolean toggle.
  • Min/max are advisory — bound-checks happen via the underlying control but not enforced server-side. Validate again on save if it matters.
Raw value
42
range Range range_field
60
Docs

Slider control for numeric or token-bound values. Supports raw numeric ranges, legacy `map` configs, and binding to a theme.json token group.

Stored: number (raw range) OR the token object (`{ key, slug, value, cssVar }`) when bound to a `tokenGroup`

Supports

  • Raw numeric range with min / max / step
  • Legacy `map` config — key/value pairs become labelled tick marks
  • `tokenGroup` binding — slider snaps between theme.json tokens (spacing scale, font sizes, etc.)
  • Allow-reset behaviour with a fallback value

Config options

min number default: "0"
Minimum value (ignored when `tokenGroup` is set).
max number default: "100"
Maximum value (ignored when `tokenGroup` is set).
step number default: "1"
Slider increment (ignored when `tokenGroup` is set).
map object | array
Legacy form. Key/value pairs that produce labelled tick marks. Stored value is the token, not the key.
tokenGroup string
Bind to a theme.json token group (e.g. `"spacing"`). The slider snaps between tokens and stores the full token object.
defaultOptionKey string
When `map` or `tokenGroup` is set, the key to use as default if the saved value is empty.

Gotchas

  • Stored shape depends on config: a raw range stores a number, a `tokenGroup` stores `{ key, slug, value, cssVar }`. Branch on type when reading.
  • When `tokenGroup` is set the displayed min/max/step are derived from the tokens, not from `min`/`max`/`step` config keys.
Raw value
60

Date & color

date Date date_field
2026-12-31
Docs

Date picker. Author clicks a button to open a calendar popover (or modal in metabox contexts). Stores a date-only ISO string.

Stored: string — ISO date like "2026-05-28", or empty string when cleared.

Supports

  • Calendar popover with Clear button
  • Works in both sidebar (popover) and metabox (modal) variants

Config options

helpText string
One-line description shown below the picker.

Gotchas

  • No min/max date config — if you need bounded dates, enforce in your render code or filter saved values server-side.
Raw value
"2026-12-31"
datetime Datetime datetime_field
2026-12-31T18:00:00
Docs

Date + time picker. Like `date`, but the popover also includes hour/minute selectors. Stores an ISO 8601 timestamp.

Stored: string — ISO 8601 like "2026-05-28T14:30:00", or empty string when cleared.

Supports

  • 12-hour time picker alongside the calendar
  • Clear button to reset to empty

Config options

helpText string
One-line description shown below the picker.

Gotchas

  • Stored as a local ISO string with no timezone suffix. Treat as the author''s local time unless you explicitly convert on the server.
Raw value
"2026-12-31T18:00:00"
color Color color_field
#5956E9
Docs

Color picker pulling its palette from the active theme.json. Renders as a small swatch that opens a popover with the theme palette and (optionally) a gradients tab.

Stored: string — hex like "#5956E9", a theme palette slug, or a CSS gradient string when gradients are enabled.

Supports

  • Theme palettes — values from `settings.color.palette` in theme.json appear automatically.
  • Gradients — when `showGradients: true`, a second tab lets the author pick a CSS gradient. Stored in the same attribute as the color (string).
  • Dual-attribute mode — set `gradientAttributeKey` to write color and gradient to separate attributes if your render path needs them apart.
  • A look of its element — bound to a CSS property (`data-gcb-look="<key>:<property>"` on the element, the properties in includes/Contract/look-props.json), the value paints that property as a style (`Contract\Fields::look_style`, src/controls/look-value.js) instead of printing as words.

Config options

showGradients boolean default: false
Show the gradient picker tab. When false (default) the popover is color-only.
gradientAttributeKey string
Optional. If set, the gradient value is stored in this attribute instead of the same one as the color. Useful when your render.php / React component expects color and gradient as separate props.

Gotchas

  • Stored value is a single string — `"#5956E9"` (color) OR `"linear-gradient(…)"` (gradient). Renderers should accept either shape unless dual-attribute mode is in use.
Raw value
"#5956E9"

Media

image Image image_field
Docs

Media library image picker. Stores a full image object — URL, alt, dimensions, optional focal point, and (when enabled) sizing / repeat / fixed-background config.

Stored: object — { url, alt, width, height, id, focalPoint?, size?, isRepeat?, isFixed? }

Supports

  • Media library picker with full image metadata
  • Optional FocalPointPicker for cover-cropping
  • Optional cover / contain / tile size selectors with custom width
  • Optional background-repeat and fixed-background toggles

Config options

enableFocalPoint boolean default: true
Show the FocalPointPicker so the author can choose a focus point for cover-cropping.
enableSizeOptions boolean default: true
Show cover / contain / tile + custom-width selectors.
enableRepeatOptions boolean default: true
Toggle for background-repeat (active when size !== "cover").
enableFixedBackground boolean default: true
Toggle for `background-attachment: fixed`.

Gotchas

  • Optional fields only appear when the corresponding `enable*` flag is on AND the author touched the control. Always destructure with defaults in React.
Raw value
{
    "url": "http://wordpressgcb.kinsta.cloud/wp-content/themes/gcb-saas-theme-headless/assets/images/project/project-3.png",
    "alt": "Sample image",
    "width": 800,
    "height": 500,
    "focalPoint": {
        "x": 0.5,
        "y": 0.35
    },
    "size": "cover",
    "customWidth": ""
}
gallery Gallery gallery_field
Docs

Multi-image picker with per-item focal point, size, repeat, and fixed-background settings. Rows are drag-to-reorder.

Stored: array of image objects — same shape as a single `image` value, one per gallery item.

Supports

  • Media library multi-select with gallery editor
  • Drag-to-reorder via dnd-kit
  • Per-image focal point, size, custom width, repeat, fixed-background
  • Re-selecting in the media library preserves per-item settings for kept images

Config options

helpText string
One-line description shown above the gallery.

Gotchas

  • Stored value is always an array. Always check `Array.isArray(value)` before mapping — empty galleries are `[]`, not `null`.
  • Each item is the full image object (url, alt, focalPoint, size, etc.), so the same renderer that handles single `image` values mostly works per-item.
Raw value
[
    {
        "id": 1,
        "url": "http://wordpressgcb.kinsta.cloud/wp-content/themes/gcb-saas-theme-headless/assets/images/project/project-1.png",
        "alt": "Tile 1",
        "width": 800,
        "height": 500
    },
    {
        "id": 2,
        "url": "http://wordpressgcb.kinsta.cloud/wp-content/themes/gcb-saas-theme-headless/assets/images/project/project-2.png",
        "alt": "Tile 2",
        "width": 800,
        "height": 500
    },
    {
        "id": 3,
        "url": "http://wordpressgcb.kinsta.cloud/wp-content/themes/gcb-saas-theme-headless/assets/images/project/project-4.png",
        "alt": "Tile 3",
        "width": 800,
        "height": 500
    },
    {
        "id": 4,
        "url": "http://wordpressgcb.kinsta.cloud/wp-content/themes/gcb-saas-theme-headless/assets/images/project/project-5.png",
        "alt": "Tile 4",
        "width": 800,
        "height": 500
    }
]
file File file_field
Docs

Non-image attachment picker (PDFs, documents, archives, etc.). Opens the WP media library and stores a small attachment object.

Stored: { id: number, url: string, filename: string, title: string }

Supports

  • Media library picker constrained by MIME type
  • Replace and Remove actions on the selected file

Config options

allowedTypes string[] default: "[\"application\", \"text\", \"image\", \"video\", \"audio\"]"
MIME top-level types to allow in the media library picker (e.g. `["application", "text"]` for PDFs and docs).

Gotchas

  • Despite the broad default `allowedTypes`, this control is intended for non-image uploads. Use `image` for images and `gallery` for collections.
  • When the value is unset the object is still present with empty fields — always check `value?.url` rather than truthiness of `value`.
Raw value
{
    "url": "http://wordpressgcb.kinsta.cloud/wp-content/themes/gcb-saas-theme-headless/assets/images/project/mobile-mockup.png",
    "filename": "mobile-mockup.png",
    "title": "Mobile mockup"
}
icon Icon icon_field
core/star-filled
Docs

Visual picker over the WP 7.0+ icon registry. Authors pick from a searchable grid; storage is just the icon name. The server resolves to SVG at render time via `WP_Icons_Registry`.

Stored: { source: "wp", name: string }

Supports

  • Searchable grid of icons from the WP icon registry
  • Namespace filter — only show icons whose name starts with `${namespace}/`
  • Explicit allow-list via `filter` for hand-curated subsets
  • Backwards-compat read of v1 dashicon values: `{ source: "dashicon", icon }` still renders, but the picker only writes the new `{ source: "wp", name }` shape.

Config options

namespace string
Restrict the picker to icons whose name starts with `${namespace}/`. Forward-compat with WP 7.1''s `register_block_icon` API.
filter string[]
Explicit allow-list of full icon names. Takes precedence over `namespace`. Use for hand-curated subsets per block.

Gotchas

  • Requires WP 7.0+. On older WP the REST endpoint 404s and the picker shows a "needs WordPress 7.0" message.
  • On vanilla WP 7.0 only `core/*` icons are registered; a `namespace: "icomoon"` filter is a no-op until something registers icons under that namespace.
  • Storage is just the name — render.php must call into the icon registry server-side to get the actual SVG. Don''t store SVG content in post_content.
Raw value
{
    "source": "wp",
    "name": "core/star-filled"
}
oembed Oembed oembed_field
https://www.youtube.com/watch?v=dQw4w9WgXcQ
Docs

URL input with a live embed preview underneath. Stores just the URL — embedding happens at render time via WP''s oEmbed handling or `<wp-embed>`.

Stored: string — the embed URL (YouTube, Vimeo, Twitter, etc.)

Supports

  • URL-typed input with placeholder for common embed providers
  • Live preview in the editor via the `<wp-embed>` web component

Config options

helpText string
One-line description shown below the input.

Gotchas

  • Stored value is a plain URL — render-side code must run it through `wp_oembed_get()` (PHP) or your own provider handler (React) to produce the embed markup.
  • No client-side validation that the URL is actually embeddable. Authors can paste any string.
Raw value
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Rich text

richtext Richtext richtext_field

Tiptap-powered editor. Supports bold, italic, lists, links.

Docs

Tiptap-backed rich text editor. Lighter than the TinyMCE `wysiwyg` control — no jQuery, no global state. Renders inline on wide surfaces and as a popover/modal in the narrow block Inspector.

Stored: string — HTML, e.g. `<p>Hello <strong>world</strong></p>`. Empty document normalises to `""`.

Supports

  • Bold / italic / strike / inline code
  • Bullet and numbered lists, blockquote
  • Headings (configurable allowed levels)
  • Links via a popover
  • Image insertion via the media library
  • Undo / redo
  • Three display modes: inline, popover, modal

Config options

headingLevels number[] default: "[2, 3, 4]"
Which heading levels appear in the block-type select.
allowImages boolean default: true
Show the insert-image toolbar button. Set to `false` for caption-style fields.
display string — "inline" | "popover" | "modal"
Force a specific display mode. Default behaviour: `popover` in sidebar variants, `inline` on wide surfaces.
placeholder string
Greyed-out hint shown on the collapsed button in popover/modal mode.

Gotchas

  • Empty editor returns `""`, not `"<p></p>"`. Required-validation works correctly.
  • The TinyMCE-based `wysiwyg` control is a backwards-compat alias for this — same component, same stored HTML shape.
Raw value
"<p>Tiptap-powered editor. Supports <strong>bold</strong>, <em>italic</em>, lists, links.</p>"
message Message message_field
—
Docs

Display-only Inspector note. Renders a coloured panel with a static message. Has no input, no stored value — purely informational. Pairs naturally with conditionalLogic for context-sensitive warnings, hints, and confirmations.

Stored: n/a — `message` has no saved value. Leave `attributeKey` off, or expect it never to be written.

Supports

  • Five variants (neutral / info / warning / danger / success), each with its own colour palette and glyph
  • Conditional display via conditionalLogic — show a warning when another field is empty, a success when it has a valid value, etc.
  • Optional label heading above the message panel

Config options

message string
The body text shown in the message panel. Preferred over `helpText`.
helpText string
Fallback body text when `message` is not set.
label string
Optional heading shown above the message panel.
variant string ("neutral" | "info" | "warning" | "danger" | "success")
Visual treatment of the panel. Defaults to "neutral" (grey). Use `warning` (amber) for "be careful," `danger` (red) for "this won't work," `success` (green) for "looks good," `info` (blue) for tips.

Gotchas

  • Not interactive — pairs well with `conditionalLogic` to display contextual hints (e.g. "Heads up: source is set to manual — pick posts below.").
  • Use the `danger` variant sparingly. If a field's value is actually invalid, prefer the field's own `validation` rules (which block save). A `danger` message is for guidance, not enforcement.
Raw value
""

Reference

post-object Post object post_object_field
Docs

Pick one or many posts (or any custom post type). Stores `{ post_type, ids[] }` — the chosen post type alongside the IDs. Omit `postType` to let the editor pick which post type to use at edit time.

Stored: `{ post_type: string, ids: number[] }` — always the canonical shape. Legacy stored values (bare IDs, or returnFormat object) are still read correctly.

Supports

  • Single or multi-select via the `multiple` flag
  • Any post type (built-in or CPT) via `postType`
  • Open-ended mode: omit `postType` to let the editor user pick the post type at edit time
  • Pairs with `conditionalLogic` for latest/manual section-block patterns

Config options

postType string
Optional. Lock the field to one (or comma-separated multiple) post type slugs. When omitted, the editor user picks via a dropdown at edit time. Stored value always carries the chosen post type alongside the IDs.
multiple boolean default: false
Allow selecting more than one. With `true` the saved ids array can have multiple entries; with `false` it has exactly one.

Gotchas

  • Switching post type in the open-ended picker clears the selected IDs — they don''t translate across post types.
  • The relationship control is a thin alias: it''s post-object with `multiple: true` forced. Same shape, same picker.
Raw value
{}
page-link Page link page_link_field
Docs

Placeholder type — currently falls through to the `url` control. The original GCB referenced this type but never shipped a real implementation, so for now it''s an alias for `url`.

Stored: { url: string, text: string, opensInNewTab: boolean } — same as `url`

Supports

  • All `url` features (display text, opens-in-new-tab toggle)

Config options

default object
Initial value, e.g. `{ "url": "", "text": "Read more", "opensInNewTab": false }`.

Gotchas

  • Today this is an alias for `url`. If you need to pick from existing site pages specifically, fall back to `post-object` with `postType: "page"`.
Raw value
{}
taxonomy Taxonomy taxonomy_field
  • Editorial #5
  • Engineering #6
Docs

Term picker for any taxonomy. Single or multi-select, with optional drag-to-reorder and a "create new term" UI. Omit `taxonomy` to let the editor pick which taxonomy to use at edit time.

Stored: `{ taxonomy: string, ids: number[] }` — always the canonical shape, whether the schema locks a taxonomy or not. Legacy stored values (bare IDs) are still read correctly.

Supports

  • Single or multi-select (`multiple`, default `true`)
  • Drag-to-reorder selected terms (multi-select only)
  • Optional inline term creation
  • Open-ended mode: omit `taxonomy` to let the editor user pick the taxonomy at edit time

Config options

taxonomy string
Optional. Lock the field to one taxonomy slug. When omitted, the editor user picks via a dropdown at edit time. Stored value always carries the chosen taxonomy alongside the IDs.
restBase string
Optional override for the REST base of a taxonomy with a non-standard rest_base. Only needed when register_taxonomy() set a custom rest_base.
multiple boolean default: true
Allow more than one term. `false` stores a single-element ids array.
allowCreateTerms boolean default: false
Show a "Create new term" form in the picker popover.

Gotchas

  • Default is `multiple: true` — opposite of `post-object` (which defaults to single). Pick deliberately.
  • REST base ≠ taxonomy slug for built-ins (`category` → `categories`, `post_tag` → `tags`). The control resolves this automatically; only override `restBase` if you registered a custom one.
  • Switching taxonomy in the open-ended picker clears the selected IDs — they don''t translate across taxonomies.
Raw value
[
    5,
    6
]
user User user_field
  • admin #1 mark.williams@kojo.com.au
Docs

WP user picker. Single or multi-select with drag-to-reorder. Stores user IDs by default, or full user objects when configured.

Stored: number (single) or number[] (multi) by default; or user-object(s) when `returnFormat: "object"`

Supports

  • Single or multi-select (`multiple`, default `false`)
  • Drag-to-reorder selected users (multi-select only)
  • Search via `/wp/v2/users`

Config options

multiple boolean default: false
Allow selecting more than one user.
returnFormat string
`"id"` (default) or `"object"`. With `"object"` the saved value is `{ id, name }`.

Gotchas

  • Default is `multiple: false` — single-select. Set `multiple: true` for author teams etc.
  • Search hits `/wp/v2/users` which only returns users with published content unless the current user can `list_users`. Editors may see different results than admins.
Raw value
{}
relationship Relationship relationship_field
Docs

Multi-select post relationship. Today this is a thin alias over `post-object` with `multiple: true` forced on — same picker, same stored shape.

Stored: number[] (default) OR post-object[] when `returnFormat: "object"` is set

Supports

  • Multi-select with drag-to-reorder
  • All `post-object` features (post type filter, taxonomy filter, return format, etc.)

Config options

postType string | string[]
WP post type slug(s) to search.
returnFormat string
`"id"` (default) stores post IDs; `"object"` stores full post objects.
enablePostTypeFilter boolean default: false
Show a post-type dropdown in the picker (when multiple types are allowed).
enableTaxonomyFilter boolean default: false
Show taxonomy term dropdowns in the picker.
filterTaxonomies { slug, label }[]
Taxonomies to surface as filters.

Gotchas

  • Functionally identical to `post-object` with `multiple: true`. Pick whichever name reads better in your `block.fields.json`.
Raw value
[
    43
]

Layout & dimension

size Size size_field
16px
Docs

CSS length input with a unit dropdown (px, em, rem, %, vh, vw). Stores a single CSS-ready string you can drop straight into `style`.

Stored: string — a CSS length like `"16px"`, `"1.5rem"`, `"100%"`. Empty string when unset.

Supports

  • Numeric input + unit selector via WP''s `UnitControl`
  • Supported units: px, em, rem, %, vh, vw
  • Plain-text fallback when `UnitControl` isn't available

Config options

helpText string
One-line description shown below the input.

Gotchas

  • Stored value is a CSS string, not a number — pass it directly to `style.width` / `style.padding` in React, or echo it inside a `style` attribute in PHP.
  • For spacing-scale presets (None / S / M / L) use `spacing` instead — `size` is for free-form CSS lengths.
Raw value
"16px"
spacing Spacing spacing_field
1rem
Docs

Preset spacing scale (None / S / M / L) with a custom-value escape hatch. Stores either a preset key or a CSS length string.

Stored: string — one of `"none" | "small" | "medium" | "large"`, OR a CSS length like `"2rem"` when the custom escape hatch is used.

Supports

  • Toggle-group of presets (defaults: None / S / M / L)
  • Custom CSS-length input with validation
  • Configurable preset list

Config options

presets { value, label }[] default: "[{ value: \"none\", label: \"None\" }, { value: \"small\", label: \"S\" }, { value: \"medium\", label: \"M\" }, { value: \"large\", label: \"L\" }]"
Override the preset toggle group.

Gotchas

  • Stored value is EITHER a preset key (`"medium"`) OR a CSS length (`"2rem"`). The renderer must map preset keys to your spacing scale before applying.
  • Custom values must match `^(\d*\.?\d+)(px|rem|em|%|vw|vh|vmin|vmax)?$` — invalid input is rejected with an inline warning.
Raw value
"1rem"
heading-level Heading heading_level_field

Sample heading

Docs

A compound control — a text input for the heading text plus a dropdown that picks the heading level (h1..h6, p, div, span). Stores both together as a single attribute.

Stored: { text: string, level: string } — text and chosen tag in one object

Supports

  • Editable heading text + semantic level in a single field
  • Restrict the level whitelist via `levels`
  • Default text and level via `default: { text, level }`

Config options

default { text, level }
Initial value. Both keys are optional; missing pieces fall back to empty string / first item of `levels`.
levels string[]
Subset of `h1, h2, h3, h4, h5, h6, p, div, span` the author can choose. Default is all six h-levels.

Gotchas

  • Always validate the saved `level` against a whitelist before rendering — never echo it as a tag name directly, otherwise a bad attribute could render arbitrary HTML.
Raw value
{
    "text": "Sample heading",
    "level": "h2"
}

Special

google-map Google map google_map_field
No Google Maps API key configured. Add one in Settings → GCB Lite to see an embedded map.
address
Sydney, NSW
lat / lng
-33.8688, 151.2093
zoom
12
Docs

Address autocomplete plus a draggable map marker. Needs a Google Maps JS API key — without one, it falls back to a plain address input that only fills `address`.

Stored: { address: string, lat: number | null, lng: number | null, zoom: number }

Supports

  • Places Autocomplete for address search
  • Interactive map preview with draggable marker
  • Graceful fallback to plain address input when no API key is configured

Config options

helpText string
One-line description shown below the control.

Gotchas

  • Requires an API key exposed via `window.gcbLite.googleMaps.apiKey`. Set it server-side using the `gcb_google_maps_api_key` filter.
  • Without an API key the control still works — but `lat`/`lng` will be `null` and there is no map preview.
  • Default zoom is 14 if not present on the saved value.
Raw value
{
    "lat": -33.8688,
    "lng": 151.2093,
    "zoom": 12,
    "address": "Sydney, NSW"
}

Repeater

repeater Links repeater links_repeater
label
Docs
url
Docs
label
GitHub
url
GitHub
Raw value
[
    {
        "_id": "r1",
        "label": "Docs",
        "url": {
            "url": "https://gutenbergcontrolblocks.com/docs",
            "text": "Docs",
            "opensInNewTab": false
        }
    },
    {
        "_id": "r2",
        "label": "GitHub",
        "url": {
            "url": "https://github.com/wordpress-gcb",
            "text": "GitHub",
            "opensInNewTab": true
        }
    }
]