Stepper

Numeric quantity control with increment and decrement buttons. Two layout variants (pill and floating), five sizes, full intent palette, min/max/step, disabled/readOnly states, and LTR/RTL support.

Installation

pnpm add @tessinaui/ui

Usage

import { Stepper } from "@tessinaui/ui";

{/* Basic uncontrolled */}
<Stepper />

{/* Controlled */}
<Stepper value={quantity} onChange={setQuantity} min={1} max={99} />

{/* Floating variant */}
<Stepper variant="floating" />

{/* With label + validation */}
<Stepper
  label="Quantity"
  intent="error"
  supportingText="Maximum quantity reached"
  value={10}
  min={1}
  max={10}
/>

{/* Custom step */}
<Stepper step={5} defaultValue={0} />

{/* RTL */}
<Stepper dir="rtl" label="الكمية" />

Playground

Preview

Showcase

Preview

API Reference

Props

Prop	Type	Default	Description
`variant`	`"pill" \| "floating"`	`"pill"`	`pill` — decrement, value and increment share one rounded-full container; `floating` — each button is a separate filled circle
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Size token
`intent`	`"none" \| "primary" \| "error" \| "warning" \| "success" \| "info"`	`"none"`	Color intent — affects button/pill background and text color
`value`	`number`	—	Controlled value
`defaultValue`	`number`	`0`	Uncontrolled initial value
`min`	`number`	`-Infinity`	Minimum value — decrement button is disabled at this value
`max`	`number`	`Infinity`	Maximum value — increment button is disabled at this value
`step`	`number`	`1`	Amount to change per click
`disabled`	`boolean`	`false`	Disable all interaction; container gets `opacity-60`
`readOnly`	`boolean`	`false`	Buttons are non-interactive (`opacity-40`, `pointer-events-none`) — value is still visible
`onChange`	`(value: number) => void`	—	Called with the new value after each change
`label`	`string`	—	Visible label rendered above the stepper
`supportingText`	`string`	—	Helper / validation text below the stepper (colored by `intent`)
`groupLabel`	`string`	`"Quantity"`	`aria-label` for the stepper group — used when no visible `label` is provided
`decrementLabel`	`string`	`"Decrease"`	`aria-label` for the − button
`incrementLabel`	`string`	`"Increase"`	`aria-label` for the + button
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Text direction. In RTL the + button is on the leading (right) side and − is on the trailing (left) side
`rounded`	`"none" \| "sm" \| "md" \| "lg" \| "full"`	`"full"`	Border radius of the pill container and pill buttons. Floating buttons always stay `rounded-full`.
`className`	`string`	—	Additional class on the root wrapper

Variants

Variant	Description
`pill`	All three elements (−, value, +) are inside one `rounded-full` container. Buttons are transparent; the pill provides the background.
`floating`	Each button is a standalone filled circle. The value floats between them without a container background.

Intents

Intent	Pill bg	Floating button bg	Text
`none`	`bg-secondary`	`bg-secondary`	`text-foreground`
`primary`	`bg-primary`	`bg-primary`	`text-on-primary`
`error`	`bg-error-light`	`bg-error-light`	`text-error`
`warning`	`bg-warning-light`	`bg-warning-light`	`text-warning`
`success`	`bg-success-light`	`bg-success-light`	`text-success`
`info`	`bg-info-light`	`bg-info-light`	`text-info`

Notes

Controlled vs uncontrolled: When value is provided, the component is fully controlled. Use defaultValue for uncontrolled usage.
Min/Max clamping: Values are always clamped between min and max. The respective button dims to opacity-30 and becomes non-interactive at the boundary.
RTL: dir="rtl" swaps the + and − button sides. The + button moves to the inline-start (right) side, matching standard RTL number-input conventions (e.g. Carbon, Fluent).
Accessibility: The control renders as role="group" with aria-label or aria-labelledby. The value uses <output aria-live="polite"> so screen readers announce changes.
readOnly vs disabled: disabled prevents all interaction and dims the whole control; readOnly dims only the buttons (the value remains clearly readable).

Stepper

On this page