Stepper

A fully interactive, accessible, user interface component that allows users to increment or decrement a value. It is commonly used for inputting numerical values, such as quantities or prices.

Quantity

Installation#

You can install this component via the shadcn CLI.

npx shadcn@latest add https://jakeisonline.com/registry/stepper.json

Usage#

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

<Stepper start={0}>
  <StepperLabel htmlFor="stepper">Quantity</StepperLabel>
  <StepperButton direction="down">-</StepperButton>
  <StepperInput id="stepper" />
  <StepperButton direction="up">+</StepperButton>
</Stepper>

Accessibility#

Adheres to the Spinbutton WAI-ARIA design pattern. At its core, this component is simply a native number field.

<StepperInput> requires the property id (string) to be set, and should match the htmlFor (string) of the <StepperLabel>.

Keyboard interactions#

Key	Action
`ArrowUp`	Increment value by `step`, or `1`
`ArrowDown`	Decrement value by `step`, or `1`
`Shift` + `ArrowUp`	Increment value by `shift`
`Shift` + `ArrowDown`	Decrement value by `shift`
`PageUp`	Increment value by `shift`
`PageDown`	Decrement value by `shift`
`Home`	Set value to `min`
`End`	Set value to `max`

Component Reference#

Stepper#

Used to wrap a single stepper field. Also provides context for all child components.

Prop	Type	Description
`start`	number	The initial value of the field. Default `0`.
`step`	number	The step size of the field. Default `1`.
`shift`	number	The step size of the field when holding `Shift` or `PageUp`/`PageDown`.
`min`	number	The minimum value of the field.
`max`	number	The maximum value of the field.

StepperLabel#

The <label> of the stepper field.

Prop	Type	Description
`htmlFor`	string	Should match the `id` of the `StepperInput`.

StepperButton#

The controller <button> of a stepper field, which users can interact with to step the value up or down.

Prop	Type	Description
`direction`	string	`up` or `down` depending on desired direction. Required.

StepperInput#

The <input> of the stepper field.

Prop	Type	Description
`id`	string	Should match the `htmlFor` of the `StepperLabel`.

StepperBadge#

An optional floating badge that displays the current value of the field.

Prop	Type	Description
`hideWhen`	number	Automatically hides the badge when the value is equal to this number. Defaults to `0`.

Examples#

Allow shift stepping#

Shift stepping allowing users to increment or decrement a value by a larger amount. When shift is set, users can shift step by holding Shift while clicking a <StepperButton>, or by using the keyboard interactions.

Quantity

Collapsing stepper fields#

You might want to display multiple quantities in a single row. For example, when ordering multiple product variants in bulk, or providing measurements for a product.