Number Field

A high-quality, unstyled React number field component with increment and decrement buttons, and a scrub area.

A numeric input element with increment and decrement buttons, and a scrub area.

Amount

Usage guidelines

Form controls must have an accessible name: It can be created using a <label> element or the Field component. See the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

import { NumberField } from '@base-ui/react/number-field';

<NumberField.Root>
  <NumberField.ScrubArea>
    <NumberField.ScrubAreaCursor />
  </NumberField.ScrubArea>
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>;

API reference

Root

Name	Type	Default	Description
`id`Optional	`string \| undefined`	—	The id of the input element.
`min`Optional	`number \| undefined`	—	The minimum value of the input element.
`max`Optional	`number \| undefined`	—	The maximum value of the input element.
`allowOutOfRange`Optional	`boolean \| undefined`	`false`	When true, direct text entry may be outside the `min`/`max` range without clamping, so native range underflow/overflow validation can occur. Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp.
`smallStep`Optional	`number \| undefined`	`0.1`	The small step value of the input element when incrementing while the meta key is held. Snaps to multiples of this value.
`step`Optional	`number \| 'any' \| undefined`	`1`	Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop. Specify `step="any"` to always disable step validation.
`largeStep`Optional	`number \| undefined`	`10`	The large step value of the input element when incrementing while the shift key is held. Snaps to multiples of this value.
`required`Optional	`boolean \| undefined`	`false`	Whether the user must enter a value before submitting a form.
`disabled`Optional	`boolean \| undefined`	`false`	Whether the component should ignore user interaction.
`readOnly`Optional	`boolean \| undefined`	`false`	Whether the user should be unable to change the field value.
`name`Optional	`string \| undefined`	—	Identifies the field when a form is submitted.
`value`Optional	`number \| null \| undefined`	—	The raw numeric value of the field.
`defaultValue`Optional	`number \| undefined`	—	The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the `value` prop instead.
`allowWheelScrub`Optional	`boolean \| undefined`	`false`	Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input.
`snapOnStep`Optional	`boolean \| undefined`	`false`	Whether the value should snap to the nearest step when incrementing or decrementing.
`format`Optional	`Intl.NumberFormatOptions \| undefined`	—	Options to format the input value.
`locale`Optional	`Intl.LocalesArgument \| undefined`	—	The locale of the input element. Defaults to the user's runtime locale.
`inputRef`Optional	`React.Ref<HTMLInputElement> \| undefined`	—	A ref to access the hidden input element.

ScrubArea

Name	Type	Default	Description
`direction`Optional	`'horizontal' \| 'vertical' \| undefined`	`horizontal`	Cursor movement direction in the scrub area.
`pixelSensitivity`Optional	`number \| undefined`	`2`	Determines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive.
`teleportDistance`Optional	`number \| undefined`	—	If specified, determines the distance that the cursor may move from the center of the scrub area before it will loop back around.

Number Field

Usage guidelines

Anatomy

API reference

Root

ScrubArea

On this page