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
import { NumberStepper } from "@plop-ui/react";
<NumberStepper label="Quantity" min={1} max={9} defaultValue={2} />
// A cart row: controlled, small, with the label kept for screen readers only.
<NumberStepper label="Quantity of Matcha latte" hideLabel size="sm"
min={1} max={9} value={qty} onValueChange={setQty} />
// At 1, − turns into a trash button. The row unmounts after onRemove: move focus to the next row.
<NumberStepper label="Quantity of Matcha latte" hideLabel size="sm"
min={1} max={9} value={qty} onValueChange={setQty}
removeLabel="Remove Matcha latte" removedMessage="Matcha latte removed"
onRemove={() => { removeRow("latte"); focusNextRow(); }} />
// Bigger steps; End jumps to max.
<NumberStepper label="Tea bags" min={0} max={100} step={10} defaultValue={20} />Change every prop live in the playground.
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
| labelrequired | ReactNode | — | The visible label, e.g. "Quantity". Required: it names the input and the − and + buttons. |
| decrementLabel | string | "Decrease {label}" when label is text, else "Decrease" | Accessible name of the − button. |
| defaultValue | number | min, or 0 when there is no lower limit | Uncontrolled initial value. |
| hideLabel | boolean | false | Hide the label visually (it stays for screen readers). Use it in tight rows like a cart. |
| incrementLabel | string | "Increase {label}" when label is text, else "Increase" | Accessible name of the + button. |
| max | number | no limit | Highest value. + disables here and End jumps to it. |
| min | number | 0 | Lowest value. − disables here and Home jumps to it. |
| onRemove | () => void | none | Called 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) => void | none | Called with the new value after every change: buttons, keys, or a typed number once it is valid. |
| removedMessage | string | "Item removed" | Announced to screen readers after the trash button is pressed. |
| removeLabel | string | "Remove item" | Accessible name of the trash button shown at `min` when `onRemove` is passed. |
| seed | string | number | generated from useId | Stable imperfections, shared by server and client. |
| size | "sm" | "md" | md | `sm` for dense rows like a cart, `md` otherwise. |
| step | number | 1 | How much − and + (and ArrowDown/ArrowUp) change the value, measured from `min`. |
| value | number | none | Controlled 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.