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/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: 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

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

stepnumber | 'any'1

Name: step
Description: 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.
Type: number | 'any' | 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.