BizzPocket

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.

ts
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:

json
{
  "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

blocks/ref-text/ref-text.tsx
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.

ts
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:

json
{
  "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

blocks/ref-rich-text/ref-rich-text.tsx
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.

ts
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:

json
{
  "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

blocks/ref-number/ref-number.tsx
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.

ts
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:

json
{
  "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

blocks/ref-boolean/ref-boolean.tsx
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.

ts
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:

json
{
  "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

blocks/ref-select/ref-select.tsx
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.

ts
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:

json
{
  "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

blocks/ref-color/ref-color.tsx
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}.

ts
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:

json
{
  "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

blocks/ref-font/ref-font.tsx
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.

ts
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:

json
{
  "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

blocks/ref-range/ref-range.tsx
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'.

ts
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:

json
{
  "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

blocks/ref-image/ref-image.tsx
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'.

ts
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:

json
{
  "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

blocks/ref-video/ref-video.tsx
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),
});

A link target from the link picker.

ts
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:

json
{
  "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

blocks/ref-link/ref-link.tsx
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().

ts
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:

json
{
  "type": "string",
  "x-bp-control": "product",
  "x-bp-label": "Value",
  "x-bp-tier": "advanced"
}

In data(): static. The build records {"k":"h"}.

Example

blocks/ref-product/ref-product.tsx
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 }).

ts
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:

json
{
  "type": "string",
  "x-bp-control": "collection",
  "x-bp-label": "Value",
  "x-bp-tier": "advanced"
}

In data(): static. The build records {"k":"h"}.

Example

blocks/ref-collection/ref-collection.tsx
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.

ts
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:

json
{
  "type": "string",
  "x-bp-control": "category",
  "x-bp-label": "Value",
  "x-bp-tier": "advanced"
}

In data(): static. The build records {"k":"h"}.

Example

blocks/ref-category/ref-category.tsx
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().

ts
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:

json
{
  "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

blocks/ref-menu/ref-menu.tsx
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.

ts
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:

json
{
  "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

blocks/ref-products/ref-products.tsx
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.

ts
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:

json
{
  "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

blocks/ref-categories/ref-categories.tsx
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.

ts
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:

json
{
  "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

blocks/ref-collections/ref-collections.tsx
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).

ts
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:

json
{
  "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

blocks/ref-list/ref-list.tsx
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.

ts
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:

json
{
  "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

blocks/ref-group/ref-group.tsx
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.

ts
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:

json
{
  "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

blocks/ref-cart/ref-cart.tsx
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.

ts
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:

json
{
  "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

blocks/ref-json/ref-json.tsx
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.

ts
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:

json
{
  "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

blocks/ref-blocks/ref-blocks.tsx
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.

ts
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:

json
{
  "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

blocks/ref-spacing/ref-spacing.tsx
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.

ts
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:

json
{
  "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

blocks/ref-color-scheme/ref-color-scheme.tsx
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.

ts
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:

json
{
  "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

blocks/ref-typography/ref-typography.tsx
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>,
});