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>
  );
}

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.

Prop	Type	Default
`name`	`string`	`undefined`
`defaultValue`	`number`	`undefined`
`value`	`number \| null`	`undefined`
`onValueChange`	`((value: number \| null, event: Event \| undefined) => void)`	`undefined`
`locale`	`Intl.LocalesArgument`	`undefined`
`snapOnStep`	`boolean`	`false`
`step`	`number`	`1`
`smallStep`	`number`	`0.1`
`largeStep`	`number`	`10`
`min`	`number`	`undefined`
`max`	`number`	`undefined`
`allowWheelScrub`	`boolean`	`false`
`format`	`Intl.NumberFormatOptions`	`undefined`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`inputRef`	`Ref<HTMLInputElement>`	`undefined`
`id`	`string`	`undefined`
`className`	`\| string \| ((state: NumberField.Root.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.Root.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`direction`	`'horizontal' \| 'vertical'`	`'horizontal'`
`pixelSensitivity`	`number`	`2`
`teleportDistance`	`number`	`undefined`
`className`	`\| string \| ((state: NumberField.ScrubArea.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.ScrubArea.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`className`	`\| string \| ((state: NumberField.ScrubAreaCursor.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.ScrubAreaCursor.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`className`	`\| string \| ((state: NumberField.Group.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.Group.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`className`	`\| string \| ((state: NumberField.Decrement.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.Decrement.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`aria-roledescription`	`string`	`'Number field'`
`className`	`\| string \| ((state: NumberField.Input.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.Input.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`className`	`\| string \| ((state: NumberField.Increment.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: NumberField.Increment.State) => ReactElement)`	`undefined`

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.