# Stepper
A numeric field with minus and plus buttons that step the value, accelerating while held.
Stepper is an open-source interaction from suiss/ui for React, React Native, SwiftUI and Jetpack Compose. The @esuiss/ui CLI copies its source into your project, so you own the code.
Source: https://ui.suiss.app/docs/interactions/stepper
**React**
**Example**
```tsx
import {
Stepper,
StepperDecrement,
StepperGroup,
StepperIncrement,
StepperInput,
StepperSeparator,
} from "@/components/interactions/stepper"
export default function StepperDemo() {
return (
)
}
```
`Stepper` recreates the iOS stepper on top of a number field primitive. It pairs an editable `StepperInput` with a segmented `StepperGroup` of `StepperDecrement` and `StepperIncrement` buttons. Each press changes the value by `step`; holding a button repeats the change after a short delay and speeds up over time. Each button disables itself when the value reaches `min` or `max`.
Use it for small, bounded quantities such as copies, servings, or scale, where people usually adjust a value by a few steps.
## Installation
### CLI
```bash title="Terminal"
npx shadcn@latest add @esuiss/stepper
```
Works in any project with a `components.json`. See [Installation](https://ui.suiss.app/docs/installation#add-components) for the one-line registry setup. Or use the suiss/ui CLI:
```bash title="Terminal"
npx @esuiss/ui@latest add interactions stepper
```
### Manual
1. Install the dependencies and add the [`cn` helper](https://ui.suiss.app/docs/installation#the-cn-helper):
```bash title="Terminal"
npm install @base-ui/react @phosphor-icons/react
```
2. Copy the source into `components/interactions/stepper.tsx`:
```tsx title="components/interactions/stepper.tsx"
"use client"
import { NumberField as NumberFieldPrimitive } from "@base-ui/react/number-field"
import { MinusIcon, PlusIcon } from "@phosphor-icons/react"
import * as React from "react"
import { cn } from "@/lib/utils"
type StepperContextProps = {
canChange: (direction: 1 | -1) => boolean
change: (direction: 1 | -1) => boolean
}
const StepperContext = React.createContext(null)
function useStepper() {
const context = React.useContext(StepperContext)
if (!context) {
throw new Error("useStepper must be used within a ")
}
return context
}
const START_DELAY = 400
const FIRST_TICK = 180
const MIN_TICK = 35
const ACCELERATION = 0.86
function decimals(number: number) {
const [mantissa = "", exponent = "0"] = String(number)
.toLowerCase()
.split("e")
const fraction = mantissa.split(".")[1]?.length ?? 0
return Math.max(0, fraction - Number(exponent))
}
function Stepper({
value: valueProp,
defaultValue = 0,
onValueChange,
min = Number.NEGATIVE_INFINITY,
max = Number.POSITIVE_INFINITY,
step = 1,
disabled = false,
readOnly = false,
className,
...props
}: Omit<
NumberFieldPrimitive.Root.Props,
"value" | "defaultValue" | "onValueChange" | "step"
> & {
step?: number
value?: number
defaultValue?: number
onValueChange?: (value: number) => void
}) {
const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue)
const value = valueProp ?? uncontrolledValue
const valueRef = React.useRef(value)
valueRef.current = value
const setValue = React.useCallback(
(next: number) => {
valueRef.current = next
if (valueProp === undefined) setUncontrolledValue(next)
onValueChange?.(next)
},
[valueProp, onValueChange]
)
const canChange = React.useCallback(
(direction: 1 | -1) =>
!disabled &&
!readOnly &&
(direction === 1 ? valueRef.current < max : valueRef.current > min),
[disabled, readOnly, min, max]
)
const change = React.useCallback(
(direction: 1 | -1) => {
if (!canChange(direction)) return false
const precision = Math.max(decimals(step), decimals(valueRef.current))
const next = Number(
(valueRef.current + direction * step).toFixed(precision)
)
setValue(Math.min(Math.max(next, min), max))
return true
},
[canChange, step, min, max, setValue]
)
return (
{
if (next !== null) setValue(next)
}}
min={min}
max={max}
step={step}
disabled={disabled}
readOnly={readOnly}
className={cn("flex items-center gap-3", className)}
{...props}
/>
)
}
function StepperInput({
className,
...props
}: NumberFieldPrimitive.Input.Props) {
return (
)
}
function StepperGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
)
}
function StepperButton({
direction,
className,
children,
...props
}: Omit, "onClick"> & { direction: 1 | -1 }) {
const { canChange, change } = useStepper()
const timerRef = React.useRef(0)
const stop = React.useCallback(() => {
window.clearTimeout(timerRef.current)
}, [])
React.useEffect(() => stop, [stop])
const repeat = (count: number) => {
timerRef.current = window.setTimeout(
() => {
if (change(direction)) repeat(count + 1)
},
count === 0
? START_DELAY
: Math.max(MIN_TICK, FIRST_TICK * ACCELERATION ** count)
)
}
return (
)
}
function StepperDecrement({
children,
...props
}: Omit, "onClick">) {
return (
{children ?? (
)}
)
}
function StepperIncrement({
children,
...props
}: Omit, "onClick">) {
return (
{children ?? (
)}
)
}
function StepperSeparator({
className,
...props
}: React.ComponentProps<"span">) {
return (
)
}
export {
Stepper,
StepperDecrement,
StepperGroup,
StepperIncrement,
StepperInput,
StepperSeparator,
}
```
3. Update the import paths to match your project.
## Usage
```tsx
import { Stepper, StepperInput, StepperGroup, StepperDecrement, StepperIncrement, StepperSeparator } from "@/components/interactions/stepper"
```
```tsx
```
- Compose `StepperInput` and a `StepperGroup` containing `StepperDecrement`, `StepperSeparator`, and `StepperIncrement` inside `Stepper`.
- The value is uncontrolled by default; pass `value` and `onValueChange` to control it.
- Other number field props, such as `min`, `max`, `disabled`, and `format`, pass through to the root.
- The buttons render minus and plus icons by default; pass children to replace them.
## Examples
### Print
A print settings list with labelled steppers, a percent format with a step of `5`, and a disabled row.
**Example**
```tsx
import * as React from "react"
import {
Stepper,
StepperDecrement,
StepperGroup,
StepperIncrement,
StepperInput,
StepperSeparator,
} from "@/components/interactions/stepper"
function StepperRow({
label,
...props
}: React.ComponentProps & { label: string }) {
const labelId = React.useId()
return (