Stepper

The Stepper component is a user interface element that allows users to increment or decrement a value. It is commonly used for inputting numerical values, such as quantities or prices.

Native form element
Optional step size and min/max
Keyboard editable, controllable & accessible
Optional shift stepping

Quantity

Usage

import {
  StepperField,
  StepperFieldButton,
  StepperFieldInput,
  StepperFieldLabel,
} from "@/components/stepper-field"

<StepperField start={0}>
  <StepperFieldLabel htmlFor="stepper">
    Quantity
  </StepperFieldLabel>
  <StepperFieldButton direction="down">
    -
  </StepperFieldButton>
  <StepperFieldInput id="stepper" />
  <StepperFieldButton direction="up">
    +
  </StepperFieldButton>
</StepperField>

Accessibility

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

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

Keyboard interaction

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

StepperField

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`.
`min`	number	Lowest allowed value of the field.
`max`	number	Highest allowed value of the field.
`step`	number	Amount the value is adjusted by. Default `1`.
`shift`	number	Amount the value is adjusted by when using Shift + arrow keys, or PageUp/PageDown

StepperFieldLabel

The <label> of the stepper field.

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

StepperFieldButton

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.

StepperFieldInput

The <input> of the stepper field.

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

StepperFieldBadge

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 <StepperFieldButton>, or by using the keyboard interactions.

Shift

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.