Stepper

A number field with the small up and down arrows beside it, stepped by clicks, held arrows and the keyboard.

@cupertinoui/stepperBase UI Number Field Registry JSON

Repeat every

weeks

"use client"

import { Stepper, StepperButtons, StepperInput } from "@/components/ui/stepper"

export default function StepperDemo() {
  return (
    <div className="flex items-center gap-2 text-mac-body text-mac-label">
      Repeat every
      <Stepper defaultValue={2} min={1} max={52}>
        <StepperInput aria-label="Weeks" className="w-12" />
        <StepperButtons />
      </Stepper>
      weeks
    </div>
  )
}

Installation

pnpm dlx shadcn@latest add @cupertinoui/stepper

The first install also adds the macOS theme. See Installation to set up the registry.

Usage

import { Stepper, StepperButtons, StepperInput } from "@/components/ui/stepper"

<Stepper defaultValue={4} min={1} max={8}>
  <StepperInput aria-label="Tab width" />
  <StepperButtons />
</Stepper>

Up and Down step the value, Page Up and Page Down step it by 10, and holding an arrow button keeps stepping. The arrows aren't separate stops for Tab, as on macOS.

Examples

Sizes

Regular beside a 24pt text field, and small beside a 20pt one for inspectors.

"use client"

import { Stepper, StepperButtons, StepperInput } from "@/components/ui/stepper"

export default function StepperSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      <Stepper defaultValue={13} min={9} max={72}>
        <StepperInput aria-label="Font size" />
        <StepperButtons />
      </Stepper>
      <Stepper size="sm" defaultValue={4} min={1} max={8}>
        <StepperInput aria-label="Tab width" />
        <StepperButtons />
      </Stepper>
    </div>
  )
}

Formatting

format takes Intl.NumberFormat options: a percentage that steps by 5%, and degrees that step by 15.

"use client"

import { Stepper, StepperButtons, StepperInput } from "@/components/ui/stepper"

export default function StepperFormat() {
  return (
    <div className="flex flex-col items-center gap-4">
      <Stepper defaultValue={0.8} min={0} max={1} step={0.05} format={{ style: "percent" }}>
        <StepperInput aria-label="Opacity" className="w-16" />
        <StepperButtons />
      </Stepper>
      <Stepper defaultValue={90} min={-180} max={180} step={15} format={{ style: "unit", unit: "degree" }}>
        <StepperInput aria-label="Rotation" className="w-16" />
        <StepperButtons />
      </Stepper>
    </div>
  )
}

API Reference

Every part forwards the props of the underlying Base UI Number Field part. The props below are the ones CupertinoUI adds or changes.

Stepper

Base UI's Number Field root: also value, onValueChange, disabled, name and the other Number Field props.

Prop	Type	Description
`size`	`"sm" \| "default"` Default: `"default"`	Small for inspectors, regular for windows.
`defaultValue`	`number`	The starting value, when uncontrolled.
`min / max`	`number`	The range the value stays in.
`step`	`number` Default: `1`	How much an arrow click or key press changes the value.
`format`	`Intl.NumberFormatOptions`	How the field shows the value, e.g. as a percentage.
`className`	`string`	Extra classes, merged with the component's own.

StepperInput

The number field, right-aligned with tabular figures.

Prop	Type	Description
`className`	`string`	Extra classes, merged with the component's own.

StepperButtons

The up and down arrows on a capsule. Leave out StepperInput for arrows alone.

Prop	Type	Description
`className`	`string`	Extra classes, merged with the component's own.