Components · Inputs
Input
A one-line text field. type: text (default), email, search, number, or password. Bind value with { "$bindState": "/path" }; it only changes on-page state and nothing is ever sent. A password field is a stand-in: it shows dots, cannot be typed into, and takes no value. description and error show under the field; hideLabel keeps the label for screen readers only; fullWidth fills the container. icon draws an icon by name (see Icon) at the start of the field, such as "search" or "mail"; it is decoration, and the label still names the field.
ExamplesLink to this section
Type a name: the text below reads the same state path.
Shown on the dashboard.
Project:
Show JSONHide JSON
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Box",
"props": { "gap": "sm", "maxWidth": "sm" },
"children": ["name", "greeting"]
},
"name": {
"type": "Input",
"props": {
"label": "Project name",
"placeholder": "Northwind",
"description": "Shown on the dashboard.",
"value": { "$bindState": "/name" },
"fullWidth": true
}
},
"greeting": {
"type": "Text",
"props": {
"tone": "muted",
"size": "sm",
"text": { "$template": "Project: ${/name}" }
}
}
},
"state": { "name": "" }
}The password field is a row of dots. A reader cannot type into it or focus it.
Show JSONHide JSON
{
"version": 1,
"root": "card",
"elements": {
"card": {
"type": "Box",
"props": {
"surface": "card",
"border": "all",
"radius": "xl",
"padding": "lg",
"gap": "md",
"maxWidth": "sm"
},
"children": ["email", "password", "submit"]
},
"email": {
"type": "Input",
"props": {
"label": "Email",
"type": "email",
"placeholder": "you@example.com",
"fullWidth": true
}
},
"password": {
"type": "Input",
"props": { "label": "Password", "type": "password", "fullWidth": true }
},
"submit": {
"type": "Button",
"props": { "label": "Sign in", "fullWidth": true }
}
}
}Enter a full email address.
Show JSONHide JSON
{
"version": 1,
"root": "box",
"elements": {
"box": {
"type": "Box",
"props": { "gap": "md", "maxWidth": "sm" },
"children": ["email", "plan", "search"]
},
"email": {
"type": "Input",
"props": {
"label": "Email",
"type": "email",
"value": "maya@",
"error": "Enter a full email address.",
"fullWidth": true
}
},
"plan": {
"type": "Input",
"props": {
"label": "Plan",
"value": "Team",
"disabled": true,
"fullWidth": true
}
},
"search": {
"type": "Input",
"props": {
"label": "Search orders",
"hideLabel": true,
"type": "search",
"placeholder": "Search orders",
"fullWidth": true
}
}
}
}The icon is decoration. Screen readers hear the label, not the icon.
Show JSONHide JSON
{
"version": 1,
"root": "box",
"elements": {
"box": {
"type": "Box",
"props": { "gap": "md", "maxWidth": "sm" },
"children": ["search", "email"]
},
"search": {
"type": "Input",
"props": {
"label": "Search",
"hideLabel": true,
"type": "search",
"placeholder": "Search projects",
"icon": "search",
"fullWidth": true
}
},
"email": {
"type": "Input",
"props": {
"label": "Email",
"type": "email",
"placeholder": "you@example.com",
"icon": "mail",
"fullWidth": true
}
}
}
}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 120 chars |
| type | "text" | "email" | "search" | "number" | "password" | — |
| placeholder | string | max 120 chars |
| value | string | max 500 chars |
| 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" | — |
| description | string | max 400 chars |
| error | string | max 300 chars |
| hideLabel | boolean | — |
| disabled | boolean | — |
RulesLink to this section
- What a reader types changes only the spec's own state, on the reader's page. Nothing is saved or sent.
typeis text, email, search, number, or password, written in the spec. A password Input is a stand-in: it takes novalue, cannot be bound, and cannot be typed into.- Password managers skip every field, and no field has a form around it.
- In a spec with a bound Input or Textarea, a Link address and Markdown, Steps, and Diagram text must be written in the spec, so typed text can never reach a link.
labelis required.hideLabelkeeps it for screen readers only.icondraws an icon by name (see Icon) at the start of the field. It is decoration, hidden from screen readers; the label still names the field.
Children and eventsLink to this section
Input is a leaf: it does not show children. Validation warns when a leaf has some; wrap them in a Stack or Card instead.
Events: change. Bind one with on to run a state action; see Actions.