Components · Layout
Box
A free-layout container for drawing screens. Children stack vertically or sit in a row (direction), with gap, padding (paddingX / paddingY override one axis), align (across the direction), justify (along it), wrap, grow (take the free room in a row), width, maxWidth (xs 320, sm 384, md 576, lg 768, xl 1024, 2xl 1280 pixels; center it with align: "center" on the parent) and minHeight. surface paints it and sets a text color that reads on it: none, page, card, muted, a hue (gray, brown, orange, yellow, green, blue, purple, pink, red), or inverse and primary, which switch everything inside to a contrasting palette and do not nest. border (all, top, bottom, start, end, x, y), radius, and shadow finish it. overflow: hidden clips children to the radius; scroll makes a row scroll sideways instead of wrapping (set label to name it). Responsive props follow the width of the page column or canvas frame, never the browser window (sm 576, md 672, lg 896 pixels): stackBelow turns a row into a column below that width; on such a row, alignBelow (start, center, end, stretch) is the align to use once it has stacked, so align: "center" on the row does not shrink each stacked child to its content, and reverseBelow draws the stacked children in reverse order (words above a picture that sits first in the row; keyboard and reading order stay as written, so do not use it across buttons, links, or fields). hideBelow and hideAbove hide the Box. label names it for screen readers.
ExamplesLink to this section
The links hide on a narrow page column.
Northwind
Show JSONHide JSON
{
"version": 1,
"root": "nav",
"elements": {
"nav": {
"type": "Box",
"props": {
"direction": "horizontal",
"align": "center",
"justify": "between",
"gap": "md",
"padding": "md",
"border": "bottom",
"label": "Site navigation"
},
"children": ["brand", "links", "cta"]
},
"brand": {
"type": "Text",
"props": { "text": "Northwind", "weight": "semibold" }
},
"links": {
"type": "Box",
"props": { "direction": "horizontal", "gap": "lg", "hideBelow": "md" },
"children": ["product", "pricing", "docs"]
},
"product": {
"type": "Link",
"props": { "label": "Product", "variant": "nav", "active": true }
},
"pricing": {
"type": "Link",
"props": { "label": "Pricing", "variant": "nav" }
},
"docs": { "type": "Link", "props": { "label": "Docs", "variant": "nav" } },
"cta": {
"type": "Button",
"props": { "label": "Sign in", "variant": "outline" }
}
}
}A row on a wide page column, a column below 672 pixels.
Know what is on every shelf
Stock counts that keep up with the stockroom.
Show JSONHide JSON
{
"version": 1,
"root": "hero",
"elements": {
"hero": {
"type": "Box",
"props": {
"direction": "horizontal",
"stackBelow": "md",
"align": "center",
"gap": "xl",
"padding": "lg"
},
"children": ["copy", "art"]
},
"copy": {
"type": "Box",
"props": { "grow": true, "gap": "md" },
"children": ["title", "lead", "action"]
},
"title": {
"type": "Heading",
"props": {
"text": "Know what is on every shelf",
"level": 2,
"size": "xl"
}
},
"lead": {
"type": "Text",
"props": {
"text": "Stock counts that keep up with the stockroom.",
"tone": "muted",
"size": "lg"
}
},
"action": { "type": "Button", "props": { "label": "Start free" } },
"art": {
"type": "Box",
"props": { "grow": true, "width": "full" },
"children": ["image"]
},
"image": {
"type": "Placeholder",
"props": {
"label": "Dashboard screenshot",
"ratio": "photo",
"radius": "xl"
}
}
}
}Each surface sets a text color that reads on it. Inverse switches everything inside to the other palette.
Card
With an edge and a soft shadow.
Blue
One of nine hue tints.
Inverse
Muted text still reads here.
Show JSONHide JSON
{
"version": 1,
"root": "row",
"elements": {
"row": {
"type": "Grid",
"props": { "columns": 3 },
"children": ["card", "tint", "band"]
},
"card": {
"type": "Box",
"props": {
"surface": "card",
"padding": "lg",
"gap": "xs",
"border": "all",
"radius": "xl",
"shadow": "sm"
},
"children": ["card-title", "card-note"]
},
"card-title": { "type": "Text", "props": { "text": "Card", "weight": "medium" } },
"card-note": {
"type": "Text",
"props": {
"text": "With an edge and a soft shadow.",
"tone": "muted",
"size": "sm"
}
},
"tint": {
"type": "Box",
"props": {
"surface": "blue",
"padding": "lg",
"gap": "xs",
"radius": "xl"
},
"children": ["tint-title", "tint-note"]
},
"tint-title": { "type": "Text", "props": { "text": "Blue", "weight": "medium" } },
"tint-note": {
"type": "Text",
"props": {
"text": "One of nine hue tints.",
"tone": "muted",
"size": "sm"
}
},
"band": {
"type": "Box",
"props": {
"surface": "inverse",
"padding": "lg",
"gap": "xs",
"radius": "xl"
},
"children": ["band-title", "band-note"]
},
"band-title": {
"type": "Text",
"props": { "text": "Inverse", "weight": "medium" }
},
"band-note": {
"type": "Text",
"props": {
"text": "Muted text still reads here.",
"tone": "muted",
"size": "sm"
}
}
}
}PropsLink to this section
Generated from the zod schema the server validates with. Unknown props are ignored with a warning. Any prop can also be a dynamic value such as { "$state": "/path" }; it is checked again once it resolves.
| Prop | Type | Limits and defaults |
|---|---|---|
| direction | "vertical" | "horizontal" | — |
| gap | "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | — |
| padding | "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | — |
| paddingX | "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | — |
| paddingY | "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | — |
| align | "start" | "center" | "end" | "stretch" | — |
| justify | "start" | "center" | "end" | "between" | — |
| wrap | boolean | — |
| grow | boolean | — |
| width | "auto" | "full" | — |
| maxWidth | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | — |
| minHeight | "sm" | "md" | "lg" | "xl" | — |
| surface | "none" | "page" | "card" | "muted" | "inverse" | "primary" | "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red" | — |
| border | "none" | "all" | "top" | "bottom" | "start" | "end" | "x" | "y" | — |
| radius | "none" | "sm" | "md" | "lg" | "xl" | "full" | — |
| shadow | "none" | "sm" | "md" | "lg" | — |
| overflow | "visible" | "hidden" | "scroll" | — |
| stackBelow | "sm" | "md" | "lg" | — |
| alignBelow | "start" | "center" | "end" | "stretch" | — |
| reverseBelow | boolean | — |
| hideBelow | "sm" | "md" | "lg" | — |
| hideAbove | "sm" | "md" | "lg" | — |
| label | string | max 120 chars |
RulesLink to this section
- Every style prop is a named step. A Box takes no CSS, colors, or pixel sizes.
- Responsive props follow the width of the page column or canvas frame, never the browser window: sm is 576, md is 672, and lg is 896 pixels.
stackBelowneedsdirection: "horizontal".hideAbovemust be a wider step thanhideBelow.alignBelowandreverseBelowneed a row withstackBelow.alignBelowis thealignto use once the row has stacked: a row withalign: "center"shrinks each stacked child to its content unlessalignBelowisstretch. Without it the row'salignapplies at every width.reverseBelowdraws the stacked children last first, so words can sit above a picture that comes first in the row. It changes what is drawn, not the order a keyboard or a screen reader follows, so use it only when at most one side holds buttons, links, or fields.overflow: "scroll"needsdirection: "horizontal"and nowrap. Give the Box alabel: while it scrolls it is a named group the keyboard can reach.- Inverse and primary do not nest: inside either, both paint the surrounding surface.
- Use a shadow on a surface that sits on the page, never on a Box inside a card.
ChildrenLink to this section
Box shows its children, in order.
It emits no events.