Field reference

Every entry in block.fields.json declares one Inspector control. The type picks the React component shown in the editor. The attributeKey picks the WP attribute name your React component receives.

Every control accepts the common keys id, attributeKey, label, helpText, default, parentPanelId, conditionalLogic, validation. The cards below list only the control-specific options.

Tip

Hover any control name to preview its full reference page, or click through. Every shipping site has the All fields page seeded with one of every control type — same code the Inspector renders, with sample data wired up.

Text input

text

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

Stored: string

Config: default, placeholder, helpText, validation.required, validation.minLength, validation.maxLength, validation.pattern

code

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

Stored: string

Config: rows, placeholder, helpText

image

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? }

Config: enableFocalPoint, enableSizeOptions, enableRepeatOptions, enableFixedBackground

richtext

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

Config: headingLevels, allowImages, display, placeholder

url

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 }

Config: default

wysiwyg

Backwards-compat alias for `richtext`. Same Tiptap-backed editor, same stored HTML shape. Kept so existing fields configs using `"type": "wysiwyg"` continue to work; new fields should use `richtext`.

Stored: string — HTML, same as `richtext`

Config: headingLevels, allowImages, display

Choice

heading

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

Config: default, levels

toggle

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

Config: options, default

checkbox

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

Config: options, default

email

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

Stored: string

Config: placeholder, helpText

repeater

A marker tag, not a sidebar control. Emit `<repeater />` from your React component and the editor swaps it for a real WP InnerBlocks UI — Add button, drag-to-reorder, child-block scoping. Most blocks don't need a `type: "repeater"` entry in their fields config.

Stored: n/a — repeater behaviour comes from the marker tag your component emits, not from a saved field value. Child data lives in `innerBlocks`.

Config: allowedblocks, addbuttonlabel, template

post-object

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.

Config: postType, multiple

number

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

Stored: number

Config: min, max, step, placeholder

select

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`

Config: options, map, tokenGroup, tokenKeys, defaultOptionKey, placeholder

radio

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`

Config: options, default

button-group

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

Config: options, default

Numeric & visual

range

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`

Config: min, max, step, map, tokenGroup, defaultOptionKey

color

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.

Config: showGradients, gradientAttributeKey

spacing

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.

Config: presets

size

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.

Config: helpText

Date & time

date

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.

Config: helpText

datetime

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.

Config: helpText

Display-only

message

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.

Config: message, helpText, label, variant

oembed

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

Config: helpText

Media

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.

Config: helpText

file

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 }

Config: allowedTypes

icon

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 }

Config: namespace, filter

Reference

taxonomy

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.

Config: taxonomy, restBase, multiple, allowCreateTerms

user

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

Config: multiple, returnFormat

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`

Config: default

relationship

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

Config: postType, returnFormat, enablePostTypeFilter, enableTaxonomyFilter, filterTaxonomies

Other

google-map

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 }

Config: helpText