Number Input for React Aria

A numeric field with buttons that step the value up and down. Typing still works.

Use it when the value has a minimum, a maximum, or a fixed step. A free-form amount with only a symbol beside it is an Input. In React, React Aria keeps the value in range and steps it with the buttons.

Installation

Anatomy

NumberInput
├── NumberInputInput
├── NumberInputGroup
├── NumberInputValueText
├── NumberInputIncrement
├── NumberInputDecrement
└── NumberInputScrubber
    └── NumberInputLabel

Usage

import {
  NumberInput, NumberInputDecrement, NumberInputGroup,
  NumberInputIncrement, NumberInputInput,
} from "@/components/ui/number-input";

<NumberInput className="w-full max-w-48" defaultValue="1">
  <NumberInputGroup>
    <NumberInputDecrement />
    <NumberInputInput />
    <NumberInputIncrement />
  </NumberInputGroup>
</NumberInput>

Accessibility

Demos

Controlled

The number lives in your state, starting at 1, and the line under the field only settles once it reads 3. Hold value when another part of the screen depends on it, or when you want to refuse a change before it sticks. The callback hands you a string, so a cleared field stays empty instead of becoming zero. Leave it uncontrolled if nothing else needs to read the number.

Disabled

disabled locks the field and both step buttons. Use it for a quantity the current plan or permission cannot change, while still showing the number that would have been edited. It is not a read-only caption: the control stays in the form, it just will not take input. Pair it with nearby text that says why it is off, or people will keep hitting the buttons.

Field Only

The group holds the input and nothing else. Drop the increment and decrement buttons when the row is narrow, like a table cell or a toolbar, and people will type the number. You still get a numeric field rather than a text box that only looks like one. If the step is awkward to type, put the buttons back.

Formatted

formatOptions takes Intl.NumberFormat options. Here the style is currency and the currency is USD, so 19 shows as dollars while the stored value stays a number. Use it for money or percents when the field should speak the format, not when you only want a symbol painted beside the box. A prefix you design yourself belongs in an input group instead.

Invalid

invalid is the error paint, before or after submit. Turn it on when the number fails a rule the field itself does not know, such as a stock check, and put the reason in a description next to it. The prop does not block typing or stepping. It only marks the control, so the message has to say what is wrong.

Mouse Wheel

allowMouseWheel lets a scroll over the focused field step the value. It stays off unless you set it, because a page scroll that crosses the input should not change a quantity. Turn it on in a tool panel where the pointer is already on the control and a wheel nudge is faster than the buttons. Leave it off in a long form.

Range

min is 0 and max is 10, with 5 as the start. The buttons stop at the ends, and a typed value outside that span is pulled back in. Set both when a percentage, a rating, or a small count cannot leave a known band. A step still applies inside the band, and if you only need to block negatives, a minimum is enough.

Scrub

NumberInputScrubber wraps the Quantity label, and dragging across it moves the value, the gesture design tools use when tiny plus and minus buttons are the slow path. Keep the buttons for people who click or use a keyboard. The scrubber is an extra handle, not a replacement for the field. Skip it where a drag fights page scrolling.

Size Lg

size set to lg raises the field and the step buttons. Pick the large size when this number is the main control on the screen, or when a coarse pointer makes the default hit area feel mean. It is the same component, not a different widget. Match it to other large fields in the form so the row does not jump.

Size Md

md is the default size, shown on its own so you can compare it with the small and large fields. Leave size unset in most forms. It lines up with the usual input height. Reach for another size only when the surrounding density actually changes, not to make one field look more important than its label.

Size Sm

size set to sm tightens the field for a toolbar, a table, or a side panel with too many rows. The buttons shrink with it, so do not use the small size as the only control on a phone. If the number is rare and the chrome should get out of the way, this is the one. Keep a visible label, because the shorter box is easy to miss.

Step

Two fields, one with step of 5 and one with step of 0.1. The first jumps in whole units, which fits inventory, and the second moves in tenths, which fits a measurement. The buttons move by that step, so pick one people can predict. A step of 7 on a price looks broken even when the math is right.

With Field

The number sits in a Field with the label Quantity and a description that says 0 to 100. min and max match that sentence. Use Field when the number needs a label, a hint, and later an error, instead of a placeholder that disappears as soon as someone types. The description is the place for the range, so do not hide it in an accessible name only.

With Input Group

The number sits in an Input Group with a euro sign before it and EUR after it, and there are no step buttons. The field has its own accessible name, because the symbols are not a label. Use this when the unit is chrome and formatOptions would force a locale currency format you do not want. The group is layout, and the number input holds the value.

FAQ

API Reference