Components · Inputs
Button
A button. Its press event can run setState, toggleState, pushState, or removeState through on. It cannot load or send data. variant: default, outline, secondary, ghost, or danger (a solid fill in the danger tone, for an action that deletes or cannot be undone). size (sm, md, lg), fullWidth, disabled, and an icon by name (see Icon) at the start or the end (iconPosition); iconOnly shows the icon alone, with label as its name for screen readers. expanded tells screen readers whether what the button opens is open (a menu toggle, a "Show more"): read it from the same state the button flips, { "$state": "/open" }, which must hold true or false. pressed tells screen readers and shows that a toggle is on (Bold, a filter chip): read it from the state the button flips, { "$state": "/bold" }, which must hold true or false. A toggle takes variant outline, secondary, or ghost, which turn solid when pressed; default and danger refuse pressed, and a button takes pressed or expanded, not both.
ExamplesLink to this section
Show JSONHide JSON
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "gap": "sm" },
"children": ["buttons", "answer"]
},
"buttons": {
"type": "Stack",
"props": { "direction": "horizontal", "gap": "sm" },
"children": ["yes", "no"]
},
"yes": {
"type": "Button",
"props": { "label": "Approve" },
"on": {
"press": {
"action": "setState",
"params": { "statePath": "/answer", "value": "Approved" }
}
}
},
"no": {
"type": "Button",
"props": { "label": "Hold", "variant": "outline" },
"on": {
"press": {
"action": "setState",
"params": { "statePath": "/answer", "value": "On hold" }
}
}
},
"answer": {
"type": "Badge",
"props": { "label": { "$template": "Choice: ${/answer}" }, "tone": "info" }
}
},
"state": { "answer": "None yet" }
}Show JSONHide JSON
{
"version": 1,
"root": "box",
"elements": {
"box": {
"type": "Box",
"props": {
"direction": "horizontal",
"wrap": true,
"align": "center",
"gap": "sm"
},
"children": ["small", "medium", "large", "more", "off"]
},
"small": {
"type": "Button",
"props": {
"label": "Filter",
"size": "sm",
"variant": "outline",
"icon": "filter"
}
},
"medium": {
"type": "Button",
"props": {
"label": "Continue",
"icon": "arrow-right",
"iconPosition": "end"
}
},
"large": {
"type": "Button",
"props": { "label": "Start free", "size": "lg" }
},
"more": {
"type": "Button",
"props": {
"label": "More actions",
"variant": "ghost",
"icon": "dots",
"iconOnly": true
}
},
"off": {
"type": "Button",
"props": {
"label": "Unavailable",
"variant": "secondary",
"disabled": true
}
}
}
}Show JSONHide JSON
{
"version": 1,
"root": "box",
"elements": {
"box": {
"type": "Box",
"props": { "maxWidth": "sm" },
"children": ["wide"]
},
"wide": {
"type": "Button",
"props": { "label": "Create account", "fullWidth": true }
}
}
}`expanded` reads the same state the button flips, so screen readers hear whether the list is open.
Show JSONHide JSON
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "gap": "sm" },
"children": ["more", "list"]
},
"more": {
"type": "Button",
"props": {
"label": "All plans",
"variant": "outline",
"icon": "chevron-down",
"iconPosition": "end",
"expanded": { "$state": "/open" }
},
"on": {
"press": { "action": "toggleState", "params": { "statePath": "/open" } }
}
},
"list": {
"type": "List",
"props": { "items": ["Starter", "Team", "Business"] },
"visible": { "$state": "/open" }
}
},
"state": { "open": false }
}`pressed` reads the same state the button flips, so one press turns Bold on, the button shows it, and screen readers hear it.
This line turns semibold while Bold is on.
Show JSONHide JSON
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "gap": "sm" },
"children": ["bold", "sample"]
},
"bold": {
"type": "Button",
"props": {
"label": "Bold",
"variant": "outline",
"size": "sm",
"pressed": { "$state": "/bold" }
},
"on": {
"press": { "action": "toggleState", "params": { "statePath": "/bold" } }
}
},
"sample": {
"type": "Text",
"props": {
"text": "This line turns semibold while Bold is on.",
"weight": {
"$cond": { "$state": "/bold" },
"$then": "semibold",
"$else": "normal"
}
}
}
},
"state": { "bold": false }
}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 |
|---|---|---|
| labelrequired | string | max 60 chars |
| variant | "default" | "outline" | "secondary" | "ghost" | "danger" | — |
| size | "sm" | "md" | "lg" | — |
| fullWidth | boolean | — |
| icon | "file-text" | "notes" | "notebook" | "book" | "book-2" | "writing" | "pencil" | "feather" | "quote" | "report" | "presentation" | "clipboard" | "archive" | "folder" | "paperclip" | "link" | "checklist" | "list-check" | "clipboard-list" | "clipboard-check" | "list-details" | "map" | "route" | "target" | "flag" | "compass" | "timeline" | "sitemap" | "hierarchy" | "gavel" | "scale" | "rocket" | "bulb" | "brain" | "search" | "microscope" | "flask" | "school" | "atom" | "language" | "code" | "terminal-2" | "brackets" | "git-branch" | "git-pull-request" | "git-merge" | "api" | "bug" | "puzzle" | "plug" | "tool" | "settings" | "adjustments" | "components" | "layout-dashboard" | "robot" | "package" | "database" | "server" | "cloud" | "cpu" | "table" | "chart-bar" | "chart-line" | "chart-pie" | "chart-dots" | "trending-up" | "stack-2" | "versions" | "calendar" | "calendar-event" | "clock" | "hourglass" | "alarm" | "refresh" | "lock" | "key" | "shield" | "shield-check" | "fingerprint" | "eye" | "users" | "user" | "message-circle" | "mail" | "bell" | "speakerphone" | "lifebuoy" | "circle-check" | "alert-triangle" | "info-circle" | "help-circle" | "ban" | "bolt" | "flame" | "sparkles" | "star" | "heart" | "trophy" | "home" | "building" | "briefcase" | "currency-dollar" | "shopping-cart" | "world" | "palette" | "photo" | "device-laptop" | "device-mobile" | "coffee" | "leaf" | "arrow-right" | "arrow-left" | "arrow-up-right" | "chevron-right" | "chevron-left" | "chevron-down" | "chevron-up" | "check" | "x" | "plus" | "minus" | "menu-2" | "dots" | "external-link" | "download" | "upload" | "send" | "player-play" | "trash" | "copy" | "filter" | "share" | "bookmark" | "tag" | "at" | "phone" | "map-pin" | "credit-card" | "gift" | "truck" | "thumb-up" | "login" | "logout" | "sun" | "moon" | "brand-github" | "brand-gitlab" | "brand-x" | "brand-linkedin" | "brand-youtube" | "brand-instagram" | "brand-facebook" | "brand-tiktok" | "brand-discord" | "brand-mastodon" | "brand-bluesky" | "brand-threads" | "brand-reddit" | "brand-twitch" | "brand-dribbble" | "brand-behance" | "brand-medium" | "brand-apple" | "brand-google" | "brand-windows" | "brand-android" | — |
| iconPosition | "start" | "end" | — |
| iconOnly | boolean | — |
| disabled | boolean | — |
| expanded | boolean | — |
| pressed | boolean | — |
RulesLink to this section
presscan run setState, toggleState, pushState, removeState, or validateForm. A button cannot load or send data.toggleStateflips the value atstatePathbetween true and false, so one button opens and closes what avisiblecondition shows: { "action": "toggleState", "params": { "statePath": "/open" } }.- Variants: default, outline, secondary, ghost, danger. Sizes: sm, md, lg.
dangeris for an action that deletes or cannot be undone: a solid fill in the danger tone. Its label reads on every Box surface and in every theme.iconOnlyneeds anicon; thelabelis then what screen readers announce.expandedsays whether what the button opens is open (a menu toggle, a "Show more"). Read it from the same path the button flips:"expanded": { "$state": "/open" }. That path must holdtrueorfalse; any other value stops the button from being shown. Leave it off a button that opens nothing.pressedsays whether a toggle is on (Bold, a filter chip, a view switch). Read it from the path the button flips:"pressed": { "$state": "/bold" }. A toggle goes from quiet to solid when pressed, so it takesvariant: "outline","secondary", or"ghost": pressed, it is filled with the text color, with its label in the page color, on every surface. The default variant is solid already and is refused, and so is danger: a one-time action, not a state that stays on. A button takespressedorexpanded, never both.
Children and eventsLink to this section
Button is a leaf: it does not show children. Validation warns when a leaf has some; wrap them in a Stack or Card instead.
Events: press. Bind one with on to run a state action; see Actions.