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_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
defaultstring- Initial value if the author hasn't edited the field.
placeholderstring- Greyed-out hint shown when the input is empty.
helpTextstring- One-line description shown below the input.
validation.requiredboolean- Block save until the field is filled in.
validation.minLengthnumber- Minimum character count.
validation.maxLengthnumber- Maximum character count. Shown as "X / Y" counter in the editor.
validation.patternstring (regex)- Regex the value must match. Enforced client- and server-side.
Raw value
"Single-line text input."
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_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
placeholderstring default: "name@example.com"- Greyed-out hint shown when the input is empty.
helpTextstring- 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_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
defaultobject- 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_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
rowsnumber default: "8"- Height of the textarea, in rows.
placeholderstring- Greyed-out hint shown when the input is empty.
helpTextstring- 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_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.
mapobject | array- Legacy form. Key/value pairs mapping option keys to richer values.
tokenGroupstring- Bind to a theme.json token group (e.g. `"color"`, `"font-size"`). Stored value becomes the full token object.
tokenKeysstring[]- When `tokenGroup` is set, restrict to these token keys only.
defaultOptionKeystring- Initial value if the field is empty.
placeholderstring- 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_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.
defaultstring- 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_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.
defaultstring[]- 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_field
Raw value
[
"react",
"next"
]
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`.
defaultboolean 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_field
Raw value
"published"
button_group_field
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.
defaultstring[]- 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_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
minnumber- Minimum allowed value.
maxnumber- Maximum allowed value.
stepnumber default: "1"- Increment for the spinner / arrow keys.
decimalsinteger- 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".
placeholderstring- 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_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
minnumber default: "0"- Minimum value (ignored when `tokenGroup` is set).
maxnumber default: "100"- Maximum value (ignored when `tokenGroup` is set).
stepnumber default: "1"- Slider increment (ignored when `tokenGroup` is set).
mapobject | array- Legacy form. Key/value pairs that produce labelled tick marks. Stored value is the token, not the key.
tokenGroupstring- Bind to a theme.json token group (e.g. `"spacing"`). The slider snaps between tokens and stores the full token object.
defaultOptionKeystring- 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_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
helpTextstring- 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_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
helpTextstring- 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_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
showGradientsboolean default: false- Show the gradient picker tab. When false (default) the popover is color-only.
gradientAttributeKeystring- 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_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
enableFocalPointboolean default: true- Show the FocalPointPicker so the author can choose a focus point for cover-cropping.
enableSizeOptionsboolean default: true- Show cover / contain / tile + custom-width selectors.
enableRepeatOptionsboolean default: true- Toggle for background-repeat (active when size !== "cover").
enableFixedBackgroundboolean 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_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
helpTextstring- 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_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
allowedTypesstring[] 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_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
namespacestring- Restrict the picker to icons whose name starts with `${namespace}/`. Forward-compat with WP 7.1''s `register_block_icon` API.
filterstring[]- 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_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
helpTextstring- 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_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
headingLevelsnumber[] default: "[2, 3, 4]"- Which heading levels appear in the block-type select.
allowImagesboolean default: true- Show the insert-image toolbar button. Set to `false` for caption-style fields.
displaystring — "inline" | "popover" | "modal"- Force a specific display mode. Default behaviour: `popover` in sidebar variants, `inline` on wide surfaces.
placeholderstring- 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_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
messagestring- The body text shown in the message panel. Preferred over `helpText`.
helpTextstring- Fallback body text when `message` is not set.
labelstring- Optional heading shown above the message panel.
variantstring ("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_field
- Hello world! #1
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
postTypestring- 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.
multipleboolean 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_field
- Hello world! #1
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
defaultobject- 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_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
taxonomystring- 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.
restBasestring- 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.
multipleboolean default: true- Allow more than one term. `false` stores a single-element ids array.
allowCreateTermsboolean 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_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
multipleboolean default: false- Allow selecting more than one user.
returnFormatstring- `"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_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
postTypestring | string[]- WP post type slug(s) to search.
returnFormatstring- `"id"` (default) stores post IDs; `"object"` stores full post objects.
enablePostTypeFilterboolean default: false- Show a post-type dropdown in the picker (when multiple types are allowed).
enableTaxonomyFilterboolean 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_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
helpTextstring- 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_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_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`.
levelsstring[]- 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_field
- 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
helpTextstring- 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
links_repeater
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
}
}
]