Skip to content
WunderUI

Number Stepper

Free

A minus button, the current number and a plus button, for a small count changed one step at a time.

npx wunderui-cli add number-stepper

Playground

5

Installation

bash
npx wunderui-cli add number-stepper

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { NumberStepper } from "@/components/ui/number-stepper"

Then use it:

tsx
import { useState } from "react"
import { NumberStepper } from "@/components/ui/number-stepper"

export function Seats() {
  const [seats, setSeats] = useState(5)

  return <NumberStepper aria-label="Seats" value={seats} onValueChange={setSeats} min={0} max={10} />
}

Expected result: You see a minus button, the number 5 and a plus button in a row, with no border. A press on the plus button makes it 6; at 10 the plus button dims and stops.

When to use

Use Number Stepper for

  • A small count changed in single steps, such as guests, items in a cart or minutes of a reminder
  • A value that always has a number, with limits that the buttons can show
  • A row in a list or a settings page, where a text field would take more room than the value deserves

Use something else for

  • Number Field for a number that people type, with arrow keys, a format and an error message
  • Slider for a value in a range where the position matters
  • Input for a number that is an identifier, such as a postcode

Format

The stepper shows the formatted value between the buttons. Use it to put the unit next to the number, such as 5 seats, 50% or $10, so the number is never read without it.

5

Limits

Min and max stop the buttons and clamp the value, and step sets how much one press changes. Without limits the number goes on in both directions.

3

States

Focus is a real state: press Tab to see the indigo border and ring. At a limit the button dims but stays focusable, so someone pressing Enter does not lose their place.

5

Keyboard interactions

The stepper is two native buttons, so the browser handles focus and activation. There are no arrow keys, Home, End or Page keys.

TaborShiftTab
Moves focus to the minus button, then to the plus button, and out. A button at its limit is dimmed but keeps its place in the order.
EnterorSpace
Presses the focused button: it changes the value by and keeps focus on the button, also when the value reaches a limit.

Behavior and motion

What the stepper does with its value, its limits and motion.

Controlled
The stepper keeps no state. The value comes from you, and a press reports the new number, already clamped to the limits.
Limits
Without limits the number goes on in both directions. A press that would pass a limit lands on the limit.
Buttons at the edge
At the minimum the minus button and at the maximum the plus button dim to 40%. They stay focusable and ignore the press, so pressing Enter again does not lose focus.
Format
The format function receives the number and returns what to show, as text or a node. It does not change the value you receive.
Announcing
The number sits in a polite live region, so a screen reader reads the new value after each press without interrupting.
No disabled or read-only state
The stepper has no disabled or read-only prop. To freeze it, set the minimum and maximum to the same value; both buttons then dim.
Width
The group is as wide as its content: two 32 px buttons, 8 px gaps and a number at least 32 px wide. A longer format such as 15 min makes it wider.
Motion
The buttons change fill quickly, and a press scales the button to 97% for a moment. The number changes in place.
Reduced motion
With reduced motion the press does not scale the button. The colour changes stay.

Anatomy

The figure marks the group, the two buttons and the number between them.

5 seats
  • A group holding a minus button, the number and a plus button, 8 px apart. It is controlled with a value and a change handler, and it has no visible label, so give it an aria-label.

  • A 32 px plain icon button named Decrease. At the minimum it dims to 40% but stays focusable, so repeated Enter does not drop focus to the page.

  • The number between the buttons, at least 32 px wide, semibold with tabular figures so it does not jiggle. It is announced politely when it changes.

  • A 32 px plain icon button named Increase. It dims and stops at the maximum in the same way.

Best practices

  • Do

    Name the group with an aria-label such as Adults or Quantity of canvas tote bags. The buttons only say Decrease and Increase; the group name tells a screen reader what they change.

  • Do

    Set min, max and step to the real limits, so the buttons stop where the values stop. The value never leaves the range.

  • Do

    Use the format function to add the unit, such as 15 min, so the number is not read without it.

  • Do

    Say why a limit was reached when it is not obvious, such as Only 5 in stock. A dimmed button alone does not explain itself.

  • Don’t

    Don't use it for a value people may want to type, such as 250. There is no text entry, so 1 to 250 takes 249 presses: use Number Field.

  • Don’t

    Don't expect arrow keys to work. It is two buttons, not a spin button, so Tab reaches each and Enter or Space presses it; use Number Field where arrow keys, Home and End matter.

  • Don’t

    Don't use it for a range where the position matters more than the number. A Slider shows where the value sits between the limits.

  • Don’t

    Don't show the number in the stepper and again in a label next to it. One place for the value is enough.

API reference

NumberStepper does not wrap a primitive: it is a div with two buttons, so it takes the attributes of a div and the props below.

A group holding a minus button, the number and a plus button, 8 px apart. It is controlled with a value and a change handler, and it has no visible label, so give it an aria-label.

PropTypeDefaultDescription
value requirednumber—The current number. The stepper is controlled, so it shows what you pass and changes only when you set a new value in .
onValueChange required(value) => void—Called with the new number after a press, already clamped to and .
minnumber-InfinityThe lowest value. The minus button dims and stops there. Defaults to minus infinity.
maxnumberInfinityThe highest value. The plus button dims and stops there. Defaults to plus infinity.
stepnumber1How much one press changes the value. Defaults to 1.
format(value) => ReactNode(n) => String(n)Turns the number into what is shown between the buttons, for example ${n} seats``. Defaults to the plain number.
classNamestring—Extra classes for the group, for example to spread the buttons across a row.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("number-stepper")
Installnpx wunderui-cli add number-stepper

The full library index for assistants is at /llms.txt.