FieldsList and object

List and object

Group fields into one value with an object, or let editors repeat a value with a list. The two nest one level, which is as far as a sidebar form stays readable.

View as Markdown

Object

f.object() groups fields into one value. Editors see the group under one label; the view gets one object:

components/sections/ImageText.schema.ts
    link: f.object({ label: f.text(), href: f.link() }).optional(),
components/sections/ImageText.tsx
      {link?.href && <a className="link-accent" href={link.href} {...linkMarks.attrs} {...linkMarks.field("label")}>{link.label}</a>}

An optional object may be left empty as a whole. Without .optional(), its required fields are required.

List

f.list(item) repeats any builder. Editors add, reorder and remove items; .min() and .max() count them, the form shows a counter, and Add stops at the limit:

components/sections/Points.schema.ts
    points: f.list(f.object({
      icon: f.select([{ value: "circle", label: "Circle" }, { value: "square", label: "Square" }, { value: "diamond", label: "Diamond" }]),
      heading: f.text(),
      text: f.text(),
    })).min(1).max(6),

A list of objects is the common shape: buttons, points, team members typed by hand. A list of one builder works too, f.list(f.text()) for a plain list of lines.

The limits

  • A list never holds a list. A list inside an object inside a list is still nested on screen, and a sidebar cannot show it legibly. A section that needs a grid of groups of lists is two sections, or a collection.
  • No references inside. f.ref() and f.refList() live at the top level of a schema, where the reference index can address them.
  • Localize the whole value. .localized() goes on the list or the object, not on a field inside it. The starter's footer localizes each link column as one value:
components/sections/Footer.schema.ts
const column = () =>
  f.object({ title: f.text(), links: f.list(f.object({ label: f.text(), href: f.link() })) }).localized();

Each limit is an error at startup, with the path that broke it.

In the canvas

A list item and an object are scopes for marks: m.item("points", i) and m.object("link") give you attrs for the item's root and field() for the fields inside, so each item's text edits in place. A mark for the whole list opens the repeater in the inspector.

Next, Reference and tags.

Edit this page on GitHubLast updated 3 Oct 2026