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.
Installation #
You can install this component via the shadcn CLI.
npx shadcn@latest add https://jakeisonline.com/components/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.
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.