# Number Stepper

A +/- increment control for a bounded numeric value.

- Category: Forms
- Page: https://wunderui.com/components/number-stepper
- Tier: Free

## Install

```bash
npx wunderui-cli add number-stepper
```

## Import

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

## Minimal usage

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.

## Usage

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

export function Example() {
  const [value, setValue] = useState(5)

  return (
    <NumberStepper
      aria-label="Quantity"
      value={value}
      onValueChange={setValue}
      min={0}
      max={10}
    />
  )
}
```

## 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

- [Number Field](https://wunderui.com/components/number-field) for a number that people type, with arrow keys, a format and an error message
- [Slider](https://wunderui.com/components/slider) for a value in a range where the position matters
- [Input](https://wunderui.com/components/input) for a number that is an identifier, such as a postcode

## Keyboard

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

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | 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. |
| `Enter` or `Space` | Presses the focused button: it changes the value by `step` and keeps focus on the button, also when the value reaches a limit. |

## Behavior

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

- `NumberStepper`: 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.
- `Decrease button`: 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.
- `Value`: 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.
- `Increase button`: 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.
- Set min, max and step to the real limits, so the buttons stop where the values stop. The value never leaves the range.
- Use the format function to add the unit, such as 15 min, so the number is not read without it.
- 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 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 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 show the number in the stepper and again in a label next to it. One place for the value is enough.

## API reference

### NumberStepper

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: number) => void |  | Called with the new number after a press, already clamped to `min` and `max`. |
| value* | number |  | The current number. The stepper is controlled, so it shows what you pass and changes only when you set a new value in `onValueChange`. |
| className | string |  | Extra classes for the group, for example `w-full justify-between` to spread the buttons across a row. |
| format | (value: number) => React.ReactNode | (n) => String(n) | Turns the number into what is shown between the buttons, for example `(n) => `${n} seats``. Defaults to the plain number. |
| max | number | Infinity | The highest value. The plus button dims and stops there. Defaults to plus infinity. |
| min | number | -Infinity | The lowest value. The minus button dims and stops there. Defaults to minus infinity. |
| step | number | 1 | How much one press changes the value. Defaults to 1. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Format: plain, with a unit, a percentage or money

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

export function Example() {
  const [value, setValue] = useState(5)

  return (
    <NumberStepper
      aria-label="Quantity"
      value={value}
      onValueChange={setValue}
      min={0}
      max={10}
    />
  )
}
```

### Limits: none, a minimum and a maximum, and a step of five

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

export function Example() {
  const [value, setValue] = useState(3)

  return (
    <NumberStepper aria-label="Points" value={value} onValueChange={setValue} />
  )
}
```

### States: rest, focus, at min and at max

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

export function Example() {
  const [value, setValue] = useState(5)

  return (
    <NumberStepper
      aria-label="Quantity"
      value={value}
      onValueChange={setValue}
      min={0}
      max={10}
    />
  )
}
```

## In context

### Guests: three counts that share a total

Each row stops where the total reaches eight, so the plus buttons of the other rows dim too. Adults start at one and cannot go lower.

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

const MAX_GUESTS = 8

const ROWS = [
  { key: "adults", label: "Adults", note: "Age 13 or older", min: 1 },
  { key: "children", label: "Children", note: "Age 2 to 12", min: 0 },
  { key: "infants", label: "Infants", note: "Under 2", min: 0 },
]

export function Example() {
  const [counts, setCounts] = useState<Record<string, number>>({ adults: 2, children: 1, infants: 0 })
  const total = Object.values(counts).reduce((sum, count) => sum + count, 0)

  return (
    <div className="flex w-full max-w-sm flex-col rounded-xl border border-border bg-card">
      <ul className="flex flex-col divide-y divide-border">
        {ROWS.map((row) => (
          <li key={row.key} className="flex items-center justify-between gap-4 px-4 py-3">
            <div className="flex flex-col">
              <span className="text-sm font-medium text-foreground">{row.label}</span>
              <span className="text-xs text-text-tertiary">{row.note}</span>
            </div>
            <NumberStepper
              aria-label={row.label}
              value={counts[row.key]}
              onValueChange={(next) => setCounts((current) => ({ ...current, [row.key]: next }))}
              min={row.min}
              max={counts[row.key] + (MAX_GUESTS - total)}
            />
          </li>
        ))}
      </ul>
      <p aria-live="polite" className="border-t border-border px-4 py-3 text-sm text-text-secondary">
        {total} of {MAX_GUESTS} guests
      </p>
    </div>
  )
}
```

### Cart line: a quantity that stops at the stock

The quantity cannot pass what is in stock, and the line says so once it gets there. The price follows the quantity and is announced politely.

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

const STOCK = 5
const PRICE = 69.98

export function Example() {
  const [quantity, setQuantity] = useState(2)

  return (
    <div className="flex w-full max-w-md flex-col gap-3 rounded-xl border border-border bg-card p-4">
      <div className="flex items-center justify-between gap-4">
        <div className="flex flex-col">
          <span className="text-sm font-medium text-foreground">Canvas tote bag</span>
          <span className="text-xs text-text-tertiary">{PRICE.toLocaleString("en-US", { style: "currency", currency: "USD" })} each</span>
        </div>
        <NumberStepper aria-label="Quantity of canvas tote bags" value={quantity} onValueChange={setQuantity} min={1} max={STOCK} />
      </div>
      <div className="flex items-baseline justify-between border-t border-border pt-3">
        <span aria-live="polite" className="text-xs text-text-tertiary">
          {quantity === STOCK ? `Only ${STOCK} in stock` : "In stock"}
        </span>
        <span className="text-sm font-semibold tabular-nums text-foreground">
          {(quantity * PRICE).toLocaleString("en-US", { style: "currency", currency: "USD" })}
        </span>
      </div>
    </div>
  )
}
```

### Reminder: a step of five with a unit

The format adds the unit and the step is five minutes, so a few presses cover the range. The sentence under it follows the value.

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

export function Example() {
  const [minutes, setMinutes] = useState(15)

  return (
    <div className="flex w-full max-w-md flex-col gap-1 rounded-xl border border-border bg-card p-4">
      <div className="flex flex-wrap items-center justify-between gap-3">
        <span className="text-sm font-medium text-foreground">Remind me before a meeting</span>
        <NumberStepper
          aria-label="Reminder time in minutes"
          value={minutes}
          onValueChange={setMinutes}
          min={5}
          max={60}
          step={5}
          format={(n) => `${n} min`}
        />
      </div>
      <p aria-live="polite" className="text-xs text-text-tertiary">
        You get a notification {minutes} minutes before each meeting.
      </p>
    </div>
  )
}
```

## For AI agents

`get_component("number-stepper")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
