Form input
Number input
Predictable numeric models, decimal-safe stepping, and consistent M3 controls.Anatomy
One container, one label, one support line. The steppers and the unit live inside the box.
- 1
Container
Owns the border and the surface; `variant`, `rounded` and `density` all act on it. On `outlined` the border is drawn by a fieldset, so the raised label cuts a real gap in it.
- 2
Label
Placed by `labelPlacement`. With `controls="scrub"` it moves into the row and becomes the drag handle.
- 3
Value
A text input with a numeric `inputmode`: it keeps the locale's separators and ignores the scroll wheel. Figures are tabular, so digits never shift while stepping.
- 4
Stepper zones
`split` puts − and + at the edges, `stacked` stacks two arrows at the trailing edge. Zones are set apart by tone and corner radius, never by a divider.
- 5
Unit
A static suffix, or a menu bound to `v-model:unit` when `units` is a list. Picking a unit relabels the value; it does not convert it.
- 6
Support line
Helper text, or the error message that replaces it.
Interactive configuration
Switch how the value is nudged and by how much, then type into the field: the draft stays exactly as typed, and the model changes only once it parses.
Split
− and + at the edges: touch-sized zones for mobile and for forms where values move in small steps.
Stacked
Two arrows at the trailing edge: compact for dense desktop tables and settings panels, too small to be the main control on touch.
No controls
Typing and the keyboard only — ArrowUp and ArrowDown still step. Right when a step means nothing to the user, such as a year.
Step sets the precision
A step of 0.5 implies one decimal place. Set `precision` only when what you display and how you step differ.
A unit relabels
Changing the unit keeps the number as it is. Convert in your own code if 512 MiB must become 0.5 GiB.
States
Each state changes one thing. Focus moves the boundary hue, error takes the boundary and the support line — and error wins when both apply.
Empty or valued
Without a value a floating label rests on the first line; a value raises it.
Primary boundary
The border or the bottom rule takes the primary colour. A read-only field takes focus without it.
Error wins
The boundary and the support line switch to the error role, also while focused. The message, not the colour, carries the meaning.
Out of the flow
Surface and ink recede, the steppers stop responding, and the field leaves the interaction.
In context
The component is shown in a working composition built from public kit primitives.