role spinbutton
Number field draft v0.1.0
Lets people enter a number, by typing it or stepping it up and down.
A number field collects a numeric value within optional bounds and steps: a quantity, a percentage, a year. It is a Text field for numbers, with the platform's own stepping control (arrow keys, a spin control) and validation of the bounds. A value whose exact figure matters less than its position in a range is a Slider; a phone number or a postal code is text, not a number: use a Text field.
Decisions
From decisions in packages/components/specs/components/number-field.spec.json, newest first. Every active decision is implemented by the spec, the tokens, the web implementation and the guidelines.
Color
-
The control is a box on the default surface outlined in the accent neutral border color; hover tints it with the surface hover color and keeps the border; invalid takes the base error border; read-only takes the level 1 surface; disabled takes the shared disabled colors. Value text is primary, the placeholder tertiary, the description secondary, the error message the error text color.
The Figma library maps no color to form controls. The accent neutral border is the lightest neutral border that keeps 3:1 against the surface in both modes (WCAG 1.4.11); the hover tint reuses the surface's own hover step.
field-colors· 2026-10-03 · v0.1.0number-field.control.background.*number-field.control.border-color.*number-field.control.color.*
Size
-
Three sizes from the Figma library's space and body scales: small (32 px high, 8 px inline padding, 14 px text), medium (40, 12, 16, the default) and large (48, 16, 20); the border is 0.6 px (stroke-width.sm) and the corners 4 px (corner-radius.xs) at every size; label, description and error message keep 14 px.
sizes· 2026-10-03 · v0.1.0number-field.control.min-height.*number-field.control.padding-inline.*number-field.control.typography.*number-field.control.border-widthnumber-field.control.border-radius
Anatomy
-
A field always has a visible label above the control; help text goes under the control as the description, and the error message under it while the field is invalid. Both are exposed as the control's description.
label-description-error· 2026-10-03 · v0.1.0WCAG 3.3.2 Labels or Instructions (A)WAI tutorials: Labeling controlsWAI tutorials: Form instructions (required fields, placeholder text, aria-describedby)APG: Describing with aria-describedby
Behaviour
-
The field is the native number input: the component styles the box; the arrow keys, the spin control and the validation of min, max and step are the browser's, and the spin control keeps its native look. Values that are not numbers (phone, postal code) use the Text field.
There is no portable way to draw the spin control from tokens, and a custom one needs script.
native-spin-control· 2026-10-03 · v0.1.0HTML: input type=number (a spinbox interface; type=text with inputmode when it does not fit)MDN: input type=number, accessibility (spinbutton; inputmode for non-numeric values)