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.
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
gallery
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
page-link
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