Number Field

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

Amount

import * as React from 'react';
import { NumberField } from '@base-ui-components/react/number-field';
import styles from './index.module.css';

export default function ExampleNumberField() {
  const id = React.useId();
  return (
    <NumberField.Root id={id} defaultValue={100} className={styles.Field}>
      <NumberField.ScrubArea className={styles.ScrubArea}>
        <label htmlFor={id} className={styles.Label}>
          Amount
        </label>
        <NumberField.ScrubAreaCursor className={styles.ScrubAreaCursor}>
          <CursorGrowIcon />
        </NumberField.ScrubAreaCursor>
      </NumberField.ScrubArea>

      <NumberField.Group className={styles.Group}>
        <NumberField.Decrement className={styles.Decrement}>
          <MinusIcon />
        </NumberField.Decrement>
        <NumberField.Input className={styles.Input} />
        <NumberField.Increment className={styles.Increment}>
          <PlusIcon />
        </NumberField.Increment>
      </NumberField.Group>
    </NumberField.Root>
  );
}

function CursorGrowIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="26"
      height="14"
      viewBox="0 0 24 14"
      fill="black"
      stroke="white"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <path d="M19.5 5.5L6.49737 5.51844V2L1 6.9999L6.5 12L6.49737 8.5L19.5 8.5V12L25 6.9999L19.5 2V5.5Z" />
    </svg>
  );
}

function PlusIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="10"
      height="10"
      viewBox="0 0 10 10"
      fill="none"
      stroke="currentcolor"
      strokeWidth="1.6"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <path d="M0 5H5M10 5H5M5 5V0M5 5V10" />
    </svg>
  );
}

function MinusIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="10"
      height="10"
      viewBox="0 0 10 10"
      fill="none"
      stroke="currentcolor"
      strokeWidth="1.6"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <path d="M0 5H10" />
    </svg>
  );
}

Usage guidelines

Form controls must have an accessible name: The input must have a meaningful label. Prefer using <Field> to provide a visible text label and description, or use the aria-label attribute as an alternative. See the forms guide for more on building form controls.

Anatomy

Import the component and assemble its parts:

Anatomy

import { NumberField } from '@base-ui-components/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

Groups all parts of the number field and manages its state. Renders a <div> element.

namestring—

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

defaultValuenumber—

Name: defaultValue
Description: The uncontrolled value of the field when it’s initially rendered.

To render a controlled number field, use the value prop instead.
Type: number | undefined

valuenumber | null—

Name: value
Description: The raw numeric value of the field.
Type: number | null | undefined

onValueChangefunction—

Name: onValueChange
Description: Callback fired when the number value changes.

The eventDetails.reason indicates what triggered the change:

'input-change' for parseable typing or programmatic text updates

'input-clear' when the field becomes empty

'input-blur' when formatting or clamping occurs on blur

'input-paste' for paste interactions

'keyboard' for keyboard input

'increment-press' / 'decrement-press' for button presses on the increment and decrement controls

'wheel' for wheel-based scrubbing

'scrub' for scrub area drags
Type: | (( value: number | null, eventDetails: NumberField.Root.ChangeEventDetails, ) => void) | undefined

onValueCommittedfunction—

Name: onValueCommitted
Description: Callback function that is fired when the value is committed. It runs later than onValueChange, when:

The input is blurred after typing a value.

The pointer is released after scrubbing or pressing the increment/decrement buttons.

It runs simultaneously with onValueChange when interacting with the keyboard.

Warning: This is a generic event not a change event.
Type: | (( value: number | null, eventDetails: NumberField.Root.CommitEventDetails, ) => void) | undefined

localeIntl.LocalesArgument—

Name: locale
Description: The locale of the input element. Defaults to the user's runtime locale.
Type: Intl.LocalesArgument

snapOnStepbooleanfalse

Name: snapOnStep
Description: Whether the value should snap to the nearest step when incrementing or decrementing.
Type: boolean | undefined
Default: false

stepnumber1

Name: step
Description: Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area.
Type: number | undefined
Default: 1

smallStepnumber0.1

Name: smallStep
Description: The small step value of the input element when incrementing while the meta key is held. Snaps to multiples of this value.
Type: number | undefined
Default: 0.1

largeStepnumber10

Name: largeStep
Description: The large step value of the input element when incrementing while the shift key is held. Snaps to multiples of this value.
Type: number | undefined
Default: 10

minnumber—

Name: min
Description: The minimum value of the input element.
Type: number | undefined

maxnumber—

Name: max
Description: The maximum value of the input element.
Type: number | undefined

allowWheelScrubbooleanfalse

Name: allowWheelScrub
Description: Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input.
Type: boolean | undefined
Default: false

formatIntl.NumberFormatOptions—

Name: format
Description: Options to format the input value.
Type: Intl.NumberFormatOptions | undefined

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

readOnlybooleanfalse

Name: readOnly
Description: Whether the user should be unable to change the field value.
Type: boolean | undefined
Default: false

requiredbooleanfalse

Name: required
Description: Whether the user must enter a value before submitting a form.
Type: boolean | undefined
Default: false

inputRefRef<HTMLInputElement>—

Name: inputRef
Description: A ref to access the hidden input element.
Type: React.Ref<HTMLInputElement> | undefined

idstring—

Name: id
Description: The id of the input element.
Type: string | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: NumberField.Root.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.Root.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.Root.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.

ScrubArea

An interactive area where the user can click and drag to change the field value. Renders a <span> element.

direction'horizontal' | 'vertical''horizontal'

Name: direction
Description: Cursor movement direction in the scrub area.
Type: 'horizontal' | 'vertical' | undefined
Default: 'horizontal'

pixelSensitivitynumber2

Name: pixelSensitivity
Description: Determines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive.
Type: number | undefined
Default: 2

teleportDistancenumber—

Name: teleportDistance
Description: If specified, determines the distance that the cursor may move from the center of the scrub area before it will loop back around.
Type: number | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: NumberField.ScrubArea.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.ScrubArea.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.ScrubArea.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.

ScrubAreaCursor

A custom element to display instead of the native cursor while using the scrub area. Renders a <span> element.

This component uses the Pointer Lock API, which may prompt the browser to display a related notification. It is disabled in Safari to avoid a layout shift that this notification causes there.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: NumberField.ScrubAreaCursor.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.ScrubAreaCursor.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.ScrubAreaCursor.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.

Group

Groups the input with the increment and decrement buttons. Renders a <div> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: NumberField.Group.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.Group.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.Group.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.

Decrement

A stepper button that decreases the field value when clicked. Renders an <button> element.

nativeButtonbooleantrue

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean | undefined
Default: true

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: NumberField.Decrement.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.Decrement.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.Decrement.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.

Input

The native input control in the number field. Renders an <input> element.

aria-roledescriptionstring'Number field'

Name: aria-roledescription
Description: A string value that provides a user-friendly name for the role of the input.
Type: string | undefined
Default: 'Number field'

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: NumberField.Input.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.Input.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.Input.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.

Increment

A stepper button that increases the field value when clicked. Renders an <button> element.

nativeButtonbooleantrue

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean | undefined
Default: true

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: NumberField.Increment.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: NumberField.Increment.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: NumberField.Increment.State, ) => ReactElement)

data-disabled

Present when the number field is disabled.

data-readonly

Present when the number field is readonly.

data-required

Present when the number field is required.

data-valid

Present when the number field is in valid state (when wrapped in Field.Root).

data-invalid

Present when the number field is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the number field's value has changed (when wrapped in Field.Root).

data-touched

Present when the number field has been touched (when wrapped in Field.Root).

data-filled

Present when the number field is filled (when wrapped in Field.Root).

data-focused

Present when the number field is focused (when wrapped in Field.Root).

data-scrubbing

Present while scrubbing.

Attribute	Description	-
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-required`	Present when the number field is required.
`data-valid`	Present when the number field is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the number field is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the number field's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the number field has been touched (when wrapped in Field.Root).
`data-filled`	Present when the number field is filled (when wrapped in Field.Root).
`data-focused`	Present when the number field is focused (when wrapped in Field.Root).
`data-scrubbing`	Present while scrubbing.