Browse the docs

NumberStepper

A quantity stepper for carts and counters: the number sits on a tilted scrap of paper between two small round stickers, − and +. A native number input does the work underneath.

Client componentWCAG AA

Contributed by @luxmoncoeur. Meet the contributors

Your cart

Matcha latte ₱180
Hojicha ₱160

Total ₱520

Change every prop live in the playground.

Props

PropTypeDefaultWhat it does
labelrequiredReactNode—The visible label, e.g. "Quantity". Required: it names the input and the − and + buttons.
decrementLabelstring"Decrease {label}" when label is text, else "Decrease"Accessible name of the − button.
defaultValuenumbermin, or 0 when there is no lower limitUncontrolled initial value.
hideLabelbooleanfalseHide the label visually (it stays for screen readers). Use it in tight rows like a cart.
incrementLabelstring"Increase {label}" when label is text, else "Increase"Accessible name of the + button.
maxnumberno limitHighest value. + disables here and End jumps to it.
minnumber0Lowest value. − disables here and Home jumps to it.
onRemove() => voidnoneCalled when the trash button is pressed. When passed, − turns into a trash button at `min` instead of disabling. The row usually unmounts afterwards: move focus somewhere sensible, like the next row or the cart heading.
onValueChange(value: number) => voidnoneCalled with the new value after every change: buttons, keys, or a typed number once it is valid.
removedMessagestring"Item removed"Announced to screen readers after the trash button is pressed.
removeLabelstring"Remove item"Accessible name of the trash button shown at `min` when `onRemove` is passed.
seedstring | numbergenerated from useIdStable imperfections, shared by server and client.
size"sm" | "md"md`sm` for dense rows like a cart, `md` otherwise.
stepnumber1How much − and + (and ArrowDown/ArrowUp) change the value, measured from `min`.
valuenumbernoneControlled value.

Also takes every attribute of <input type="number"> (300 more, e.g. onClick, className, aria-*).

Use it well

DoUse it for small whole quantities, like items in a cart or guests at a table. Set min and max so − and + know when to stop, and give each one a label that says what it counts. In a cart, pass onRemove so − becomes a trash button at the minimum.
Don'tUse it for large or imprecise ranges (use Slider) or for values that aren't counts, like phone numbers or PINs (use TextField).

Accessibility

  • A native input type=number with a visible label, so it is announced as a spinbutton with its value. hideLabel keeps the label for screen readers in tight rows.
  • ArrowUp and ArrowDown change it by step; Home and End jump to min and max. Enter or leaving the field clamps and snaps what was typed.
  • The − and + buttons are named after the label ("Increase Quantity of Matcha latte"), point at the input with aria-controls, and disable at the limits.
  • When a focused button disables at a limit, focus moves to the input instead of the page. Button presses announce the new value through a polite live region.
  • With onRemove, − turns into a native trash button at min (named by removeLabel, default "Remove item") instead of disabling. It is the same button, so keyboard focus stays on it when it swaps.
  • Pressing trash announces removedMessage (default "Item removed") through a polite region on the page body, so it is still read when the row unmounts.
  • The trash button turns tomato on hover and press; the color is never the only signal (the icon and name change too).
  • After onRemove the row usually unmounts and focus would drop to the page: move it somewhere sensible, like the next row's stepper or the cart heading.
  • Every target is at least 44px at both sizes (48px −, + and trash buttons, 44px input); name, disabled, readOnly and form reset work like any input.
  • Surface text tokens keep the label readable on all five surfaces in light and dark. Reduced motion stops the outline boil and highlighter swipe.
Five stamps!

All aboard.

You took the whole tour. Here's Holo Pip, a foil sticker for riders who finish. It's in your playground tray now, for good.