Fields reference
On this page
Every field builder on f, read from packages/theme/src/fields.ts. For each one: its options, the editor control it produces in blocks.json, the prop type render receives, how a saved value is read, how a data() need that uses it is evaluated on the server, its limits and a minimal example. For a guided tour, read Fields.
Summary
| Builder | Prop type | Editor control | Static in data() |
|---|---|---|---|
f.text() |
string |
text | yes (t) |
f.richText() |
string |
richtext | no: runtime |
f.number() |
number |
number | yes (n) |
f.boolean() |
boolean |
toggle | yes (b) |
f.select() |
T |
select | yes (e) |
f.color() |
string |
color | no: runtime |
f.font() |
FontValue |
font | no: runtime |
f.range() |
number |
range | no: runtime |
f.image() |
ImageValue | undefined |
image | no: runtime |
f.video() |
VideoValue | undefined |
video | no: runtime |
f.link() |
string | undefined |
link | no: runtime |
f.product() |
string | undefined |
product | yes (h) |
f.collection() |
string | undefined |
collection | yes (h) |
f.category() |
string | undefined |
category | yes (h) |
f.menu() |
string | undefined |
menu | yes (m) |
f.products() |
string[] |
products | yes (l) |
f.categories() |
string[] |
one category picker per item | yes (l) |
f.collections() |
string[] |
one collection picker per item | yes (l) |
f.list() |
Array<PropsOf<I>> |
none | no: runtime |
f.group() |
PropsOf<G> |
none | no: runtime |
f.cart() |
none (a trait: CSS variables on the block wrapper, not a prop) | none | no: runtime |
f.json() |
T |
none | yes (raw) |
f.blocks() |
ReactNode[] |
"blocks inside" list | n/a (not a prop) |
f.spacing() |
none (a trait: CSS variables on the block wrapper, not a prop) | spacing | n/a (not a prop) |
f.colorScheme() |
none (a trait: CSS variables on the block wrapper, not a prop) | colorScheme | n/a (not a prop) |
f.typography() |
none (a trait: CSS variables on the block wrapper, not a prop) | typography | n/a (not a prop) |
Options every field takes
Most builders take these (traits and f.blocks() take fewer; each section lists exactly what its builder accepts).
| Option | Meaning |
|---|---|
label |
Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
Help text under the control in the editor (x-bp-help). |
group |
Editor group heading the control is listed under (x-bp-group). |
tier |
'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
How data() reads a field
A static data() need is evaluated by the page endpoint (Rust), which gets the raw saved props. So the build records, on each $prop reference, how the field reads a raw value ({"$prop":"count","c":{"k":"n","min":1,"max":12,"d":8}}), and the server applies the same rules as readProps. The rules are pinned on both sides: packages/theme/src/needs.ts (Coercion) and apps/backend/crates/bp-svc-storefront-page/src/coerce.rs. d is the fallback (the field's default; absent for an optional field).
k |
Rule |
|---|---|
n |
number: a finite number or numeric string, clamped to min/max |
t |
text: a trimmed string, cut to max UTF-16 units |
e |
select: a string that is one of v |
b |
boolean: true/false only |
l |
resource list: unique non-empty trimmed strings, at most max |
h |
handle: a non-empty trimmed string |
f.json() needs no coercion (the raw value or the default is passed through). A data() that passes any of these to a need is runtime (the block runs data() itself on every request; bizzpocket build says why): f.richText(), f.color(), f.font(), f.range(), f.image(), f.video(), f.link(), f.list(), f.group(), f.cart(). Read them in render instead, or use a field kind the server can coerce. See Data.
f.text
A short string: headings, button labels, captions.
f.text<const O extends TextOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
multiline |
boolean |
false |
Use a textarea (x-bp-control: textarea) instead of a one-line input. |
maxLength |
number |
none | Longest value kept, in UTF-16 units; longer saved text is cut to this length. Written to the JSON Schema as maxLength. |
placeholder |
string |
none | Accepted by the type, but not written to blocks.json today: it has no effect in the editor. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string; string | undefined with optional: true.
Reading saved values: Strings are trimmed and cut to maxLength. Anything else (a number, an object, null) reads the default.
For the sample f.text({ default: "Hello", maxLength: 80 }): a saved block without the key reads "Hello"; a new block starts with "Hello".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"maxLength": 80,
"x-bp-control": "text",
"x-bp-label": "Value",
"x-bp-tier": "basic",
"default": "Hello"
}In data(): static. The build records {"k":"t","max":80,"d":"Hello"}.
Limits: No length cap unless you set maxLength. A key ending in href/Href gets the link control.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.text() example',
fields: { title: f.text({ default: 'New arrivals', maxLength: 80 }) },
render: ({ title }) => <h2>{title}</h2>,
});f.richText
Formatted text (HTML) the seller writes in a rich-text editor, sanitised before render.
f.richText<const O extends RichTextOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
maxLength |
number |
200,000 | Values longer than this (default 200 000 chars) fall back to the default instead of being sanitised. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string; string | undefined with optional: true.
Reading saved values: Strings are trimmed and sanitised (allowed tags only, see the limits reference). A value longer than the cap reads the default as a whole; it is never cut mid-tag.
For the sample f.richText({ default: "<p>Hi</p>" }): a saved block without the key reads "<p>Hi</p>"; a new block starts with "<p>Hi</p>".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "richtext",
"x-bp-label": "Value",
"x-bp-tier": "basic",
"default": "<p>Hi</p>"
}In data(): runtime: field kind richText cannot be coerced on the server.
Limits: At most maxLength characters, default 200,000. Elements nested deeper than 256 are flattened.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.richText() example',
fields: { body: f.richText({ default: '<p>Free shipping over ₹999</p>' }) },
render: ({ body }) => <div dangerouslySetInnerHTML={{ __html: body }} />,
});f.number
A number, optionally clamped and whole.
f.number<const O extends NumberOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
min |
number |
none | Smallest value; a saved value below it is raised to it (JSON Schema minimum). Also the empty value when there is no default. |
max |
number |
none | Largest value; a saved value above it is lowered to it (JSON Schema maximum). |
step |
number |
none | Editor step (JSON Schema multipleOf). Not enforced when reading. |
integer |
boolean |
false |
Whole numbers only: a saved fraction is truncated, and the editor's JSON Schema type is integer. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
number |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: number; number | undefined with optional: true.
Reading saved values: A finite number, or a numeric string, is truncated when integer, then clamped to min/max. Anything else reads the default.
For the sample f.number({ default: 8, min: 1, max: 24, integer: !0 }): a saved block without the key reads 8; a new block starts with 8.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "integer",
"minimum": 1,
"maximum": 24,
"x-bp-control": "number",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": 8
}In data(): static. The build records {"k":"n","min":1,"max":24,"d":8}.
Limits: Only what you set with min/max.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.number() example',
fields: { count: f.number({ default: 8, min: 1, max: 24, integer: true }) },
render: ({ count }) => <p>{count} products</p>,
});f.boolean
An on/off toggle.
f.boolean<const O extends BaseOpts<boolean> = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
boolean |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: boolean; boolean | undefined with optional: true.
Reading saved values: Only true/false are kept; anything else ("true", 1) reads the default.
For the sample f.boolean({ default: !0 }): a saved block without the key reads true; a new block starts with true.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "boolean",
"x-bp-control": "toggle",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": true
}In data(): static. The build records {"k":"b","d":true}.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.boolean() example',
fields: { showPrice: f.boolean({ default: true }) },
render: ({ showPrice }) => <p>{showPrice ? 'with price' : 'no price'}</p>,
});f.select
One of a fixed list of strings. The prop type is the union of the values.
f.select<const T extends string, const O extends BaseOpts<T> = {}>(options: readonly (T | { value: T; label: string })[], o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
T |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: T; T | undefined with optional: true.
Reading saved values: A string equal to one of the values (not trimmed). Anything else reads the default, else the first option.
For the sample f.select(["grid", "list"], { default: "grid" }): a saved block without the key reads "grid"; a new block starts with "grid".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"enum": [
"grid",
"list"
],
"x-bp-control": "select",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": "grid"
}In data(): static. The build records {"k":"e","v":["grid","list"],"d":"grid"}.
Limits: Values are strings. Pass { value, label } objects to show a label other than the value.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.select() example',
fields: { layout: f.select(['grid', { value: 'list', label: 'List view' }], { default: 'grid' }) },
render: ({ layout }) => <div data-layout={layout} />,
});f.color
A colour value from the colour picker.
f.color<const O extends BaseOpts<string> = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string; string | undefined with optional: true.
Reading saved values: Only #rgb, #rgba, #rrggbb, #rrggbbaa, rgb()/rgba()/hsl()/hsla() with plain numbers, or var(--token) are kept. Anything else reads the default.
For the sample f.color({ default: "#111111" }): a saved block without the key reads "#111111"; a new block starts with "#111111".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "color",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": "#111111"
}In data(): runtime: field kind color cannot be coerced on the server.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.color() example',
fields: { accent: f.color({ default: '#c0392b' }) },
render: ({ accent }) => <div style={{ background: accent }} />,
});f.font
A font from the curated catalog (the same fonts the platform self-hosts). The block reads a ready font-family value, never a raw string.
From the JSDoc: A font of the curated catalog (fonts.ts). Saved as the font id; read as a {@link FontValue}.
f.font<const O extends FontOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
categories |
readonly FontCategory[] |
none | Catalog categories the editor offers (sans, serif, display, mono). Default: all. |
weights |
readonly number[] |
none | Weights the block asks the host to load. Default: every weight the font has. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: FontValue; FontValue | undefined with optional: true.
Reading saved values: The saved value is a font id. A block reads { id, family, weights } built from the catalog: an id the field does not offer reads the field default. family is a safe font-family declaration with a metric-matched fallback.
For the sample f.font({ default: "inter" }): a saved block without the key reads {"id":"inter","family":"\"Inter\", \"Inter Fallback\", system-ui, sans-serif","weights":[400,600,700]}; a new block starts with "inter".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"enum": [
"inter",
"roboto",
"poppins",
"montserrat",
"open-sans",
"lato",
"nunito",
"raleway",
"mukta",
"dm-sans",
"playfair-display",
"merriweather",
"dm-serif-display",
"cormorant-garamond",
"cinzel",
"prata",
"jetbrains-mono",
"system-sans",
"system-serif"
],
"x-bp-option-labels": {
"inter": "Inter",
"roboto": "Roboto",
"poppins": "Poppins",
"montserrat": "Montserrat",
"open-sans": "Open Sans",
"lato": "Lato",
"nunito": "Nunito",
"raleway": "Raleway",
"mukta": "Mukta",
"dm-sans": "DM Sans",
"playfair-display": "Playfair Display",
"merriweather": "Merriweather",
"dm-serif-display": "DM Serif Display",
"cormorant-garamond": "Cormorant Garamond",
"cinzel": "Cinzel",
"prata": "Prata",
"jetbrains-mono": "JetBrains Mono",
"system-sans": "System sans",
"system-serif": "System serif"
},
"x-bp-control": "font",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": "inter"
}In data(): runtime: field kind font cannot be coerced on the server.
Limits: Only catalog fonts. categories limits the choices (sans, serif, display, mono); weights limits the weights the host loads.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.font() example',
fields: { heading: f.font({ default: 'inter' }) },
render: ({ heading }) => <h2 style={{ fontFamily: heading.family }}>Hello</h2>,
});f.range
A number picked on a slider between fixed bounds, with an optional unit label (spacing, radius, duration).
From the JSDoc: A number slider: clamped to [min, max] and snapped to step when read. Render gets the number.
f.range<const O extends RangeOpts>(o: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
min |
number |
none | Smallest value on the slider (required). |
max |
number |
none | Largest value on the slider (required). |
step |
number |
1 |
Slider step, default 1. Saved values snap to it, counted from min. |
unit |
"" | "px" | "rem" | "em" | "%" | "vw" | "vh" | "ms" | "s" |
none | Unit label shown next to the value in the editor (x-bp-unit). Default: none. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
number |
min |
The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: number; number | undefined with optional: true.
Reading saved values: A number or a plain decimal string is clamped to min/max and snapped to the nearest step from min. Anything else reads the default, else min.
For the sample f.range({ min: 0, max: 48, step: 4, unit: "px", default: 16 }): a saved block without the key reads 16; a new block starts with 16.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "number",
"minimum": 0,
"maximum": 48,
"multipleOf": 4,
"x-bp-step": 4,
"x-bp-unit": "px",
"x-bp-control": "range",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": 16
}In data(): runtime: field kind range cannot be coerced on the server.
Limits: min and max are required. unit is one of px, rem, em, %, vw, vh, ms, s or none; it is only a label, the prop stays a number.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.range() example',
fields: { gap: f.range({ min: 0, max: 48, step: 4, unit: 'px', default: 16 }) },
render: ({ gap }) => <div style={{ gap: `${gap}px` }} />,
});f.image
An image from the media picker: { src, alt? }, or a URL string with format: 'url'.
f.image<const O extends ImageOpts | ImageUrlOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" | "basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
ImageValue | string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
format |
"object" | "url" |
'object' |
'url' stores and renders a plain URL string instead of an object; the editor still shows the picker. |
Prop type in render: ImageValue | undefined; string | undefined with format: 'url'.
Reading saved values: Needs a non-empty src that is an https or root-relative URL (see safe URLs); otherwise the default (undefined without one). alt is kept when it is a string. With format: 'url' a string, or an object's src, is read the same way.
For the sample f.image(): a saved block without the key reads undefined; a new block starts with undefined.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"src": {
"type": "string"
},
"alt": {
"type": "string"
}
},
"x-bp-control": "image",
"x-bp-label": "Value",
"x-bp-tier": "basic"
}In data(): runtime: field kind image cannot be coerced on the server.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.image() example',
fields: { hero: f.image() },
render: ({ hero }) => (hero ? <img src={hero.src} alt={hero.alt ?? ''} /> : null),
});f.video
An uploaded video: { src, poster? }, or a URL string with format: 'url'.
f.video<const O extends VideoOpts | VideoUrlOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" | "basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
VideoValue | string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
format |
"object" | "url" |
'object' |
'url' stores and renders a plain URL string instead of an object; the editor still shows the picker. |
Prop type in render: VideoValue | undefined; string | undefined with format: 'url'.
Reading saved values: src (and poster, when present) must be an https or root-relative URL; otherwise the default. An unsafe poster is dropped, the video kept.
For the sample f.video(): a saved block without the key reads undefined; a new block starts with undefined.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"src": {
"type": "string"
},
"poster": {
"type": "string"
}
},
"x-bp-control": "video",
"x-bp-label": "Value",
"x-bp-tier": "basic"
}In data(): runtime: field kind video cannot be coerced on the server.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.video() example',
fields: { clip: f.video() },
render: ({ clip }) => (clip ? <video src={clip.src} poster={clip.poster} muted /> : null),
});f.link
A link target from the link picker.
f.link(o?: BaseOpts<string>)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string | undefined.
Reading saved values: A trimmed non-empty string that is root-relative (not //), a #anchor, or an absolute https:, mailto: or tel: URL. Anything else (including http: and javascript:) reads the default.
For the sample f.link({ default: "/collections/all" }): a saved block without the key reads "/collections/all"; a new block starts with "/collections/all".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "link",
"x-bp-label": "Value",
"x-bp-tier": "basic",
"default": "/collections/all"
}In data(): runtime: field kind link cannot be coerced on the server.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.link() example',
fields: { href: f.link({ default: '/collections/all' }) },
render: ({ href }) => <a href={href ?? '/'}>Shop</a>,
});f.product
One product handle, picked in the product picker. Pass it to product({ handle }) in data().
f.product(o?: RouteHandleOpts)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
fromRoute |
boolean |
none | On a page of the matching type (product, collection or category) with an empty saved value, the host fills the field with the route's handle before data() runs, so the block shows the page's own entity and stays static. A saved value wins. Needs the backend release that sends the route handle: until then the field reads empty. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string | undefined.
Reading saved values: A trimmed non-empty string; anything else reads the default (undefined).
For the sample f.product(): a saved block without the key reads undefined; a new block starts with undefined.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "product",
"x-bp-label": "Value",
"x-bp-tier": "advanced"
}In data(): static. The build records {"k":"h"}.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.product() example',
fields: { handle: f.product() },
render: ({ handle }) => <p>{handle}</p>,
});f.collection
One collection handle, picked in the collection picker. Pass it to products({ collection }).
f.collection(o?: RouteHandleOpts)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
fromRoute |
boolean |
none | On a page of the matching type (product, collection or category) with an empty saved value, the host fills the field with the route's handle before data() runs, so the block shows the page's own entity and stays static. A saved value wins. Needs the backend release that sends the route handle: until then the field reads empty. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string | undefined.
Reading saved values: A trimmed non-empty string; anything else reads the default (undefined).
For the sample f.collection(): a saved block without the key reads undefined; a new block starts with undefined.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "collection",
"x-bp-label": "Value",
"x-bp-tier": "advanced"
}In data(): static. The build records {"k":"h"}.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.collection() example',
fields: { collection: f.collection() },
render: ({ collection }) => <p>{collection}</p>,
});f.category
One category handle, picked in the category picker.
f.category(o?: RouteHandleOpts)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
fromRoute |
boolean |
none | On a page of the matching type (product, collection or category) with an empty saved value, the host fills the field with the route's handle before data() runs, so the block shows the page's own entity and stays static. A saved value wins. Needs the backend release that sends the route handle: until then the field reads empty. |
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string | undefined.
Reading saved values: A trimmed non-empty string; anything else reads the default (undefined).
For the sample f.category(): a saved block without the key reads undefined; a new block starts with undefined.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "category",
"x-bp-label": "Value",
"x-bp-tier": "advanced"
}In data(): static. The build records {"k":"h"}.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.category() example',
fields: { category: f.category() },
render: ({ category }) => <p>{category}</p>,
});f.menu
One navigation menu handle. Pass it to menu({ handle }) in data().
f.menu(o?: BaseOpts<string>)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
string |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: string | undefined.
Reading saved values: A trimmed non-empty string; anything else reads the default.
For the sample f.menu({ default: "main-menu" }): a saved block without the key reads "main-menu"; a new block starts with "main-menu".
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "string",
"x-bp-control": "menu",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": "main-menu"
}In data(): static. The build records {"k":"m","d":"main-menu"}.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.menu() example',
fields: { menu: f.menu({ default: 'main-menu' }) },
render: ({ menu }) => <nav data-menu={menu} />,
});f.products
An ordered list of product handles from the products picker.
From the JSDoc: Product handles picked in the editor (products picker), in order.
f.products<const O extends ResourceListOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
optional |
boolean |
false |
A saved block (and a new one, unless default is set) without the key reads undefined, not []. |
default |
readonly string[] |
[] |
The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
max |
number |
50 | Largest value; a saved value above it is lowered to it (JSON Schema maximum). |
Prop type in render: string[]; string[] | undefined with optional: true.
Reading saved values: An array: non-empty trimmed strings, duplicates removed (first kept), at most max. A non-array reads the default ([]).
For the sample f.products({ max: 12 }): a saved block without the key reads []; a new block starts with [].
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "array",
"items": {
"type": "string"
},
"maxItems": 12,
"x-bp-control": "products",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": []
}In data(): static. The build records {"k":"l","max":12,"d":[]}.
Limits: At most max items, default 50.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.products() example',
fields: { picks: f.products({ max: 12 }) },
render: ({ picks }) => <p>{picks.length} picked</p>,
});f.categories
An ordered list of category ids; the editor shows one category picker per item.
From the JSDoc: Category ids picked in the editor (one category picker per item), in order.
f.categories<const O extends ResourceListOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
optional |
boolean |
false |
A saved block (and a new one, unless default is set) without the key reads undefined, not []. |
default |
readonly string[] |
[] |
The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
max |
number |
50 | Largest value; a saved value above it is lowered to it (JSON Schema maximum). |
Prop type in render: string[]; string[] | undefined with optional: true.
Reading saved values: Same as f.products(): unique non-empty trimmed strings, at most max.
For the sample f.categories(): a saved block without the key reads []; a new block starts with [].
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "array",
"items": {
"type": "string",
"x-bp-control": "category",
"x-bp-label": "Category"
},
"maxItems": 50,
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": []
}In data(): static. The build records {"k":"l","max":50,"d":[]}.
Limits: At most max items, default 50.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.categories() example',
fields: { ids: f.categories({ max: 6 }) },
render: ({ ids }) => <p>{ids.length} categories</p>,
});f.collections
An ordered list of collection ids; the editor shows one collection picker per item.
From the JSDoc: Collection ids picked in the editor (one collection picker per item), in order.
f.collections<const O extends ResourceListOpts = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
optional |
boolean |
false |
A saved block (and a new one, unless default is set) without the key reads undefined, not []. |
default |
readonly string[] |
[] |
The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
max |
number |
50 | Largest value; a saved value above it is lowered to it (JSON Schema maximum). |
Prop type in render: string[]; string[] | undefined with optional: true.
Reading saved values: Same as f.products(): unique non-empty trimmed strings, at most max.
For the sample f.collections(): a saved block without the key reads []; a new block starts with [].
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "array",
"items": {
"type": "string",
"x-bp-control": "collection",
"x-bp-label": "Collection"
},
"maxItems": 50,
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": []
}In data(): static. The build records {"k":"l","max":50,"d":[]}.
Limits: At most max items, default 50.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.collections() example',
fields: { ids: f.collections({ max: 6 }) },
render: ({ ids }) => <p>{ids.length} collections</p>,
});f.list
A repeatable list of items, each a map of fields (slides, FAQ entries, logos).
f.list<const I extends FieldMap, const O extends ListOpts<I> = {}>(item: I, o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (host-filled or legacy data), like every other field's hidden. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of [] / the default items (which a NEW block still starts with). For 2.x lists that were optional in the schema but filled by defaultProps. |
min |
number |
none | Fewest items the editor asks for (JSON Schema minItems). Not enforced when reading. |
max |
number |
none | Most items: extra saved items are dropped, and the editor stops at it (maxItems). |
default |
readonly ListDefaultItem<I>[] |
[] |
Items the list starts with (demo content). Each item is read like saved content (readProps(item, el)), so keys it omits take the item fields' defaults; max applies. Saved content, even [], replaces it. |
Prop type in render: Array<PropsOf<I>>; Array<PropsOf<I>> | undefined with optional: true.
Reading saved values: An array, cut to max; every item is read with the item fields like a block of its own. A non-array reads the default items.
For the sample f.list({ title: f.text(), href: f.link() }, { max: 6, default: [{ title: "First" }] }): a saved block without the key reads [{"title":"First"}]; a new block starts with [{"title":"First"}].
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Title",
"x-bp-tier": "basic",
"default": ""
},
"href": {
"type": "string",
"x-bp-control": "link",
"x-bp-label": "Href",
"x-bp-tier": "basic"
}
}
},
"maxItems": 6,
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": [
{
"title": "First"
}
]
}In data(): runtime: field kind list cannot be coerced on the server.
Limits: At most max items when set; no cap otherwise. min only goes to the editor (minItems). An f.blocks() field may not sit inside a list.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.list() example',
fields: { slides: f.list({ title: f.text(), image: f.image() }, { max: 6, default: [{ title: 'Summer' }] }) },
render: ({ slides }) => <ul>{slides.map((s, i) => <li key={i}>{s.title}</li>)}</ul>,
});f.group
A nested object of fields, shown as one group in the editor.
f.group<const G extends FieldMap, const O extends BaseOpts<PropsOf<G>> = {}>(fields: G, o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
PropsOf<G> |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: PropsOf<G>; PropsOf<G> | undefined with optional: true.
Reading saved values: An object is read with the group fields; anything else reads the default (an empty group: every field at its own default).
For the sample f.group({ title: f.text({ default: "Hi" }), dark: f.boolean() }): a saved block without the key reads {"title":"Hi","dark":false}; a new block starts with {"title":"Hi","dark":false}.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"title": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Title",
"x-bp-tier": "basic",
"default": "Hi"
},
"dark": {
"type": "boolean",
"x-bp-control": "toggle",
"x-bp-label": "Dark",
"x-bp-tier": "advanced",
"default": false
}
},
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": {
"title": "Hi",
"dark": false
}
}In data(): runtime: field kind group cannot be coerced on the server.
Limits: An f.blocks() field may not sit inside a group.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.group() example',
fields: { cta: f.group({ label: f.text({ default: 'Shop now' }), href: f.link() }) },
render: ({ cta }) => <a href={cta.href ?? '/'}>{cta.label}</a>,
});f.cart
The cart the storefront server-renders into a cart block. Declare it as initialCart: f.cart(); it is not an editor setting.
f.cart()No options.
Prop type in render: none (a trait: CSS variables on the block wrapper, not a prop).
Reading saved values: The injected cart is checked against the cart shape (a lines list and a totals group). A value of the wrong shape reads undefined, never an error, and a cart sent without totals reads with totals: undefined. The field is optional, so a page the storefront does not fill reads undefined.
For the sample f.cart(): a saved block without the key reads undefined; a new block starts with undefined.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lineId": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Line id",
"x-bp-tier": "basic",
"x-bp-hidden": true,
"default": ""
},
"productId": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Product id",
"x-bp-tier": "basic",
"x-bp-hidden": true,
"default": ""
},
"variantId": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Variant id",
"x-bp-tier": "basic",
"x-bp-hidden": true,
"default": ""
},
"handle": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Handle",
"x-bp-tier": "basic",
"default": ""
},
"title": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Title",
"x-bp-tier": "basic",
"default": ""
},
"quantity": {
"type": "number",
"minimum": 1,
"multipleOf": 1,
"x-bp-control": "number",
"x-bp-label": "Quantity",
"x-bp-tier": "advanced",
"default": 1
},
"price": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"x-bp-control": "number",
"x-bp-label": "Amount",
"x-bp-tier": "advanced",
"default": 0
},
"currency": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Currency",
"x-bp-tier": "basic",
"default": ""
}
},
"x-bp-label": "Price",
"x-bp-tier": "advanced",
"default": {
"amount": 0,
"currency": ""
}
},
"image": {
"type": "object",
"properties": {
"src": {
"type": "string"
},
"alt": {
"type": "string"
}
},
"x-bp-control": "image",
"x-bp-label": "Image",
"x-bp-tier": "basic"
}
}
},
"x-bp-label": "Lines",
"x-bp-tier": "advanced",
"default": []
},
"totals": {
"type": "object",
"properties": {
"subtotal": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"x-bp-control": "number",
"x-bp-label": "Amount",
"x-bp-tier": "advanced",
"default": 0
},
"currency": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Currency",
"x-bp-tier": "basic",
"default": ""
}
},
"x-bp-label": "Subtotal",
"x-bp-tier": "advanced",
"default": {
"amount": 0,
"currency": ""
}
},
"total": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"x-bp-control": "number",
"x-bp-label": "Amount",
"x-bp-tier": "advanced",
"default": 0
},
"currency": {
"type": "string",
"x-bp-control": "text",
"x-bp-label": "Currency",
"x-bp-tier": "basic",
"default": ""
}
},
"x-bp-label": "Total",
"x-bp-tier": "advanced",
"default": {
"amount": 0,
"currency": ""
}
}
},
"x-bp-label": "Totals",
"x-bp-tier": "advanced",
"default": {
"subtotal": {
"amount": 0,
"currency": ""
},
"total": {
"amount": 0,
"currency": ""
}
}
}
},
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"x-bp-hidden": true
}In data(): runtime: field kind group cannot be coerced on the server.
Limits: The prop name initialCart is the contract: the Next storefront fills it on the cart page only. Nowhere else, and on the Bun renderer, it is undefined. Hidden from the editor, no options.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.cart() example',
fields: { initialCart: f.cart() },
render: ({ initialCart }) => <p>{cartModel(initialCart).lines.length} items</p>,
});f.json
Any JSON value, passed through as saved. You type it: f.json<MyShape>(). The editor shows no control.
f.json<T = unknown, const O extends BaseOpts<T> = {}>(o?: O)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
help |
string |
none | Help text under the control in the editor (x-bp-help). |
group |
string |
none | Editor group heading the control is listed under (x-bp-group). |
tier |
"basic" | "advanced" |
none | 'basic' shows the control in the editor's Simple mode, 'advanced' only in Advanced. When no field of the block sets tier, text, rich text, image, video and link fields are basic and the rest advanced; once any field sets it, untiered fields are advanced. |
hidden |
boolean |
false |
Not shown in the editor (x-bp-hidden): for values the host fills or legacy data. Text fields whose key is id, slug, key or ends in Id/Slug/Key are hidden automatically. |
default |
NonNullable<T> |
see below | The value a saved block without the key reads, and what a new block starts with. Also the fallback for a saved value that does not coerce. |
optional |
boolean |
false |
A saved block without the key reads undefined instead of the default, and the prop type widens with | undefined. A new block still starts with default when one is set. |
Prop type in render: T; T | undefined with optional: true.
Reading saved values: Passed through unchanged (no validation); undefined/null read the default.
For the sample f.json({ default: { a: 1 } }): a saved block without the key reads {"a":1}; a new block starts with {"a":1}.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"default": {
"a": 1
}
}In data(): static, passed through as saved (no coercion).
Limits: Not validated: check the shape in render before you trust it.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.json() example',
fields: { config: f.json<{ columns: number }>({ default: { columns: 3 } }) },
render: ({ config }) => <div data-cols={config.columns} />,
});f.blocks
Child blocks: makes the block a container. render gets the rendered children under this key as ReactNode[]. See Container blocks.
f.blocks(o?: BlocksOpts)Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label of the "blocks inside" list. |
help |
string |
none | Help text for the "blocks inside" list. |
allow |
readonly string[] |
['*'] (any block) |
Which blocks the seller may put inside. Default: any block. |
max |
number |
24 | Most children rendered; more saved children are skipped. |
Prop type in render: ReactNode[].
Reading saved values: Never read from props: the key is always [] in readProps, and the renderer fills it with the rendered children (saved as the block's children).
Editor (blocks.json) — the block's schema gets x-bp-children instead of a property, for the sample above:
{
"childrenField": "value",
"allow": [
"category:media",
"hero"
],
"max": 6
}In data(): not a prop, so data() cannot read it.
Limits: One per block, top level only (not inside f.list/f.group). At most max children, default 24; extra children are not rendered. Containers nest at most 3 levels below a top-level block.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.blocks() example',
fields: { items: f.blocks({ allow: ['category:media'], max: 6 }) },
render: ({ items }) => <div className="row">{items}</div>,
});f.spacing
A trait, not a prop: the seller picks top/right/bottom/left spacing tokens and the block wrapper gets --bp-spacing-* CSS variables.
f.spacing(o?: { label?: string })Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
Prop type in render: none (a trait: CSS variables on the block wrapper, not a prop).
Reading saved values: Not passed to render. Each side must be a token name ([\w-]+) and becomes var(--spacing-<name>).
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"top": {
"type": "string",
"x-bp-css-var": "--bp-spacing-top"
},
"right": {
"type": "string",
"x-bp-css-var": "--bp-spacing-right"
},
"bottom": {
"type": "string",
"x-bp-css-var": "--bp-spacing-bottom"
},
"left": {
"type": "string",
"x-bp-css-var": "--bp-spacing-left"
}
},
"x-bp-control": "spacing",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"x-bp-css-var": "--bp-spacing"
}In data(): not a prop, so data() cannot read it.
Limits: One spacing trait per block.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.spacing() example',
fields: { space: f.spacing() },
render: () => <section style={{ paddingTop: 'var(--bp-spacing-top)' }} />,
});f.colorScheme
A trait: background and text colour tokens, as --bp-color-background / --bp-color-text.
f.colorScheme(o?: { label?: string })Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
Prop type in render: none (a trait: CSS variables on the block wrapper, not a prop).
Reading saved values: Not passed to render. Each value must be a token name and becomes var(--colors-<name>).
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"background": {
"type": "string",
"x-bp-css-var": "--bp-color-background"
},
"text": {
"type": "string",
"x-bp-css-var": "--bp-color-text"
}
},
"x-bp-control": "colorScheme",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"x-bp-css-var": "--bp-color"
}In data(): not a prop, so data() cannot read it.
Limits: One colour-scheme trait per block.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.colorScheme() example',
fields: { scheme: f.colorScheme() },
render: () => <section style={{ background: 'var(--bp-color-background)' }} />,
});f.typography
A trait: font token, size and weight, as --bp-type-font / --bp-type-size / --bp-type-weight.
f.typography(o?: { label?: string })Options
| Option | Type | Default | Meaning |
|---|---|---|---|
label |
string |
none | Editor label. Default: the key, humanised (ctaHref becomes "Cta href"). |
Prop type in render: none (a trait: CSS variables on the block wrapper, not a prop).
Reading saved values: Not passed to render. font must be a token name (var(--fonts-<name>)); size and weight are raw values matching [\w.%-]+.
Editor (blocks.json) — the field's propsSchema property, for the sample above:
{
"type": "object",
"properties": {
"font": {
"type": "string",
"x-bp-css-var": "--bp-type-font"
},
"size": {
"type": "string",
"x-bp-css-var": "--bp-type-size"
},
"weight": {
"type": "string",
"x-bp-css-var": "--bp-type-weight"
}
},
"x-bp-control": "typography",
"x-bp-label": "Value",
"x-bp-tier": "advanced",
"x-bp-css-var": "--bp-type"
}In data(): not a prop, so data() cannot read it.
Limits: One typography trait per block.
Example
import { block, f } from '@bizzpocket/theme';
export default block({
name: 'f.typography() example',
fields: { type: f.typography() },
render: () => <h2 style={{ fontFamily: 'var(--bp-type-font)' }}>Hi</h2>,
});