NumberField

Stable

Edit in Studio

Numeric input with decrease and increase buttons, arrow-key stepping, min and max, and locale-aware formatting.

Updated Oct 16, 2026

Workbench

Rendered with the real component

Light

Required approvals

Dark

Required approvals

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.

Required approvals

Set min and max

Bounds disable the buttons at the edges and stop impossible values.

Base spacing (px)

Don't

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

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.

26 tokens 18 semantic or component, change with theme and brand 4 density, change with comfortable or compact 4 from the shared scales

Container .root

--control-height-md --font-family-sans
sm .sm

--control-height-sm
lg .lg

--control-height-lg
Bordered box .group

--border-width-default --input-border --input-radius --input-bg --input-text --motion-duration-instant --motion-easing-standard
Bordered box, hover @media (hover: hover) .group:hover:not([data-disabled], [data-invalid], :has([aria-invalid="true"]))

--input-border-hover
Bordered box .group:focus-within

--focus-ring-color --border-width-default
Bordered box .group[data-invalid]

--input-border-invalid
Bordered box .group[data-invalid]:focus-within

--border-width-default --input-border-invalid
Bordered box .group[data-disabled]

--color-border-default --input-bg-disabled --color-text-disabled
Value input .input

--control-padding-x-sm --font-size-200
Unit .suffix

--space-2 --color-text-muted --font-size-200
Decrease or increase button .stepper

--color-text-muted --motion-duration-instant --motion-easing-standard
Decrease or increase button .stepper:first-child

--border-width-default --color-border-default
Decrease or increase button .stepper:last-child

--border-width-default --color-border-default
Decrease or increase button, hover @media (hover: hover) .stepper:hover:not([data-disabled])

--color-surface-hover --color-text-default
Decrease or increase button .stepper:active:not([data-disabled])

--color-surface-pressed
Decrease or increase button, focus .stepper:focus-visible

--focus-ring-width --focus-ring-color
Decrease or increase button .stepper[data-disabled]

--color-text-disabled
Value input @media (pointer: coarse) .input

--font-size-300

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.

Required approvals

<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

Changelog

New

Forms: Field (label, description, error wired by Base UI Field) and Input rebuilt on it (prefix, suffix, sizes; label, hint and error props kept). New Textarea (autosize, character count), Select (groups, descriptions), Combobox (filtering, async loading and empty states, multiple with chips), Checkbox (indeterminate, parent), CheckboxGroup, RadioGroup, Switch, Slider (single and range), NumberField (steppers, units) and Form (server errors with a focusable error summary, FormActions footer).

Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026

All release notes