Number Input

A field that allows user input of numeric values.

You can explore the number-input component in the following curated examples.

Anatomy

<NumberInput.Root>
  <NumberInput.Label />
  <NumberInput.Scrubber />
  <NumberInput.Control>
    <NumberInput.Input />
    <NumberInput.IncrementTrigger />
    <NumberInput.DecrementTrigger />
  </NumberInput.Control>
</NumberInput.Root>

Examples

Min and Max

Pass the min prop or max prop to set an upper and lower limit for the input. By default, the input will restrict the value to stay within the specified range.

To allow values outside the min/max range, set clampValueOnBlur to false.

Precision

In some cases, you might need the value to be rounded to specific decimal points. Set the formatOptions and provide Intl.NumberFormatOptions such as maximumFractionDigits or minimumFractionDigits.

Scrubbing

The NumberInput supports the scrubber interaction pattern. To use this pattern, render the NumberInput.Scrubber component. It uses the Pointer lock API and tracks the pointer movement. It also renders a virtual cursor which mimics the real cursor's pointer.

Mouse Wheel

The NumberInput exposes a way to increment/decrement the value using the mouse wheel event. To activate this, set the allowMouseWheel prop to true.

Formatting

To apply custom formatting to the input's value, set the formatOptions and provide Intl.NumberFormatOptions such as style and currency.

Field

The Field component helps manage form-related state and accessibility attributes of a number input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Root Provider

An alternative way to control the number input is to use the RootProvider component and the useNumberInput hook. This way you can access the state and methods from outside the component.

Guides

Scrubber

The NumberInput.Scrubber component provides an interactive scrub area that allows users to drag to change the input value. It renders as a <div> element and displays a custom cursor element during scrubbing interactions.

This component utilizes the Pointer Lock API for smooth dragging interactions.

Note: Browsers may show a notification when the Pointer Lock API is activated. The scrubber is automatically disabled in Safari to prevent layout shifts.

Controlled

When controlling the NumberInput component, it's recommended to use string values instead of converting to numbers. This is especially important when using formatOptions for currency or locale-specific formatting.

const [value, setValue] = useState('0')

<NumberInput.Root value={value} onValueChange={(details) => setValue(details.value)}>
  {/* ... */}
</NumberInput.Root>

Converting values to numbers can cause issues with locale-specific formatting, particularly for currencies that use different decimal and thousands separators (e.g., 1.523,30 vs 1,523.30). By keeping values as strings, you preserve the correct formatting and avoid parsing issues.

If you need to submit a numeric value in your form, use a hidden input that reads valueAsNumber from NumberInput.Context:

<NumberInput.Root value={value} onValueChange={(details) => setValue(details.value)}>
  <NumberInput.Input />
  <NumberInput.Context>
    {(context) => <input type="hidden" name="amount" value={context.valueAsNumber} />}
  </NumberInput.Context>
</NumberInput.Root>

API Reference

Props

Root

Renders a <div> element.

Control

Renders a <div> element.

DecrementTrigger

Renders a <button> element.

IncrementTrigger

Renders a <button> element.

Input

Renders a <input> element.

Label

Renders a <label> element.

RootProvider

Renders a <div> element.

Scrubber

Renders a <div> element.

ValueText

Renders a <span> element.

Context

API

Accessibility

Complies with the Spinbutton WAI-ARIA design pattern.

Keyboard Support