NumberField
Preview appears after the next Storybook update.
<NumberField />When to use
Use it for
- Exact numbers within known bounds: approvals, columns, spacing steps, retry counts.
- suffix for the unit (px, ms, %), format for currency or percent.
Not for
- Identifiers that only look like numbers (zip codes, ids, phone numbers): use Input with inputMode numeric.
- Rough values where position matters: use Slider.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Set min and max
Bounds disable the buttons at the edges and stop impossible values.
Unit in the label and in the value
Say it once, in the suffix: "Base spacing" with px, not "Base spacing (px)" plus px.
Accessibility
- Base UI NumberField: a text input with role textbox and aria-roledescription Number field; Arrow Up and Down step, Shift uses largeStep.
- The decrease and increase buttons are named and disabled at min and max.
- Inherits label, description and error from Field; invalid sets aria-invalid and a danger edge.
- Values use tabular figures so digits do not jump while stepping.
Content guidelines
- Label names the quantity, the suffix names the unit.
- Errors give the allowed range: "Use 1 to 5."
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/NumberField/NumberField.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Container
.root - sm
.sm - lg
.lg - Bordered box
.group - Bordered box, hover
@media (hover: hover) .group:hover:not([data-disabled], [data-invalid], :has([aria-invalid="true"])) - Bordered box
.group:focus-within - Bordered box
.group[data-invalid] - Bordered box
.group[data-invalid]:focus-within - Bordered box
.group[data-disabled] - Value input
.input - Unit
.suffix - Decrease or increase button
.stepper - Decrease or increase button
.stepper:first-child - Decrease or increase button
.stepper:last-child - Decrease or increase button, hover
@media (hover: hover) .stepper:hover:not([data-disabled]) - Decrease or increase button
.stepper:active:not([data-disabled]) - Decrease or increase button, focus
.stepper:focus-visible - Decrease or increase button
.stepper[data-disabled] - Value input
@media (pointer: coarse) .input
Motion and interaction
NumberField animates on hover and press. Try it in the preview at the top.
| When | What changes | Duration | Easing |
|---|---|---|---|
| Hover | Background, border and text color | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Press | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
With reduced motion turned on, every change happens at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/NumberField/NumberField.tsx, so this table cannot drift from the code.
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | none | Visible label. When set, the NumberField wraps itself in a Field. Leave unset inside a Field. |
hint | ReactNode | none | No description in the code yet. |
error | ReactNode | none | No description in the code yet. |
value | number | null | none | No description in the code yet. |
defaultValue | number | none | No description in the code yet. |
onValueChange | (value: number | null) => void | none | No description in the code yet. |
min | number | none | No description in the code yet. |
max | number | none | No description in the code yet. |
step | number | none | Amount for the buttons and arrow keys. Shift+arrow uses largeStep. Default 1. |
largeStep | number | none | No description in the code yet. |
format | Intl.NumberFormatOptions | none | Intl number format, for example `{ style: 'unit', unit: 'pixel' }` or `{ maximumFractionDigits: 2 }`. |
suffix | ReactNode | none | Unit or symbol shown after the value inside the box, for example "px". |
hideSteppers | boolean | false | Hide the increment and decrement buttons (keyboard and wheel still work). |
size | 'sm' | 'md' | 'lg' | 'md' | No description in the code yet. |
name | string | none | No description in the code yet. |
placeholder | string | none | No description in the code yet. |
disabled | boolean | none | No description in the code yet. |
readOnly | boolean | none | No description in the code yet. |
required | boolean | none | No description in the code yet. |
hideLabel | boolean | none | No description in the code yet. |
id | string | none | No description in the code yet. |
className | string | none | No description in the code yet. |
Playground
Change the props and see the real NumberField update. Controls are generated from the TypeScript props; nothing here changes the system.
<NumberField label="Required approvals" />Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open NumberField in Storybook).
Embed Storybook stories here (4)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
WithUnit
Invalid
AllStates
From the code Generated from the component, not editable here.
Changelog
- Fix
Component specs treat a button or a select (including the Base UI part that renders one, read from Base UI's docs) as border-box: NumberField steppers are their height token wide again
v1.0.0, Nov 11, 2026