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.
Object
f.object() groups fields into one value. Editors see the group under one label; the view gets one object:
link: f.object({ label: f.text(), href: f.link() }).optional(), {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:
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()andf.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:
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.