suiss/uim · Interaction
Stepper
A number input with minus and plus buttons that step the value, repeat while held and play a selection haptic.
Stepper is an open-source mobile interaction from suiss/uim for React Native and Expo, with SwiftUI and Jetpack Compose versions built from the same design tokens. The @esuiss/uim CLI copies its source into your project, so you own the code.


import { Stepper, StepperDecrement, StepperGroup, StepperIncrement, StepperInput, StepperSeparator } from "@/components/interactions/stepper"
export function StepperExample() {
return (
<Stepper defaultValue={1} min={0} max={10}>
<StepperInput accessibilityLabel="Quantity" />
<StepperGroup>
<StepperDecrement />
<StepperSeparator />
<StepperIncrement />
</StepperGroup>
</Stepper>
)
}import EsuissUI
import SwiftUI
struct StepperParts: View {
var body: some View {
StepperInput()
StepperGroup {
StepperDecrement()
StepperSeparator()
StepperIncrement()
}
}
}
struct StepperQuantity: View {
@State private var value = 1
var body: some View {
ValueStepper(value: $value, in: 0...10) {
StepperParts()
}
.accessibilityLabel(Text("Quantity"))
}
}import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableDoubleStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import com.esuiss.ui.interactions.Stepper
import com.esuiss.ui.interactions.StepperDecrement
import com.esuiss.ui.interactions.StepperGroup
import com.esuiss.ui.interactions.StepperIncrement
import com.esuiss.ui.interactions.StepperInput
import com.esuiss.ui.interactions.StepperSeparator
@Composable
fun StepperControls() {
StepperGroup {
StepperDecrement()
StepperSeparator()
StepperIncrement()
}
}
@Composable
fun StepperDefault() {
var value by rememberSaveable { mutableDoubleStateOf(1.0) }
Row {
Stepper(value = value, onValueChange = { value = it }, min = 0.0, max = 10.0) {
StepperInput(contentDescription = "Quantity")
StepperControls()
}
}
}Stepper is a number field laid out as a right-aligned value followed by a field holding minus and plus buttons, inset from its edges. Each step snaps to step and stays within min and max, and a button that can go no further is shown as disabled.
Pressing and holding a button steps once, then repeats every 60 ms after 400 ms. The value can also be typed. Use it for quantities, copies or percentages in settings rows.
Installation
$ pnpm dlx @esuiss/uim@latest add stepper$ pnpm dlx @esuiss/uim@latest add stepper --platform swift$ pnpm dlx @esuiss/uim@latest add stepper --platform kotlinThe CLI also adds what it builds on: Icon.
Manual
- Install the dependencies:
npx expo install cn phosphor-react-native react-native-svg-
Add the pieces it builds on: Icon, and the primitives
components/primitives/number-field.tsx,components/primitives/use-render.tsx. -
Copy the source into
components/interactions/stepper.tsx:
import { cn } from "cn"
import { MinusIcon, PlusIcon } from "phosphor-react-native"
import type * as React from "react"
import { View, type ViewProps } from "react-native"
import * as NumberFieldPrimitive from "@/components/primitives/number-field"
import { resolveClassName } from "@/components/primitives/use-render"
import { Icon } from "@/components/ui/icon"
function Stepper({
value,
defaultValue = 0,
onValueChange,
className,
...props
}: Omit<
React.ComponentProps<typeof NumberFieldPrimitive.Root>,- Update the import paths to match your project.
- Install the dependencies:
npx expo install cn nativewind phosphor-react-native react-native-svg-
Add the pieces it builds on: Icon, and the primitives
components/primitives/number-field.tsx,components/primitives/use-render.tsx. -
Copy the source into
components/interactions/stepper.tsx:
import { cn } from "cn"
import { cssInterop } from "nativewind"
import { MinusIcon, PlusIcon } from "phosphor-react-native"
import type * as React from "react"
import { TextInput, View, type ViewProps } from "react-native"
import * as NumberFieldPrimitive from "@/components/primitives/number-field"
import { resolveClassName } from "@/components/primitives/use-render"
import { Icon } from "@/components/ui/icon"
declare module "react-native" {
interface TextInputProps {
cursorColorClassName?: string
selectionColorClassName?: string
}
}- Update the import paths to match your project.
- Install the dependencies:
npx expo install phosphor-react-native react-native-svg-
Add the pieces it builds on: Icon, and the primitives
components/primitives/number-field.tsx,components/primitives/use-render.tsx. -
Copy the source into
components/interactions/stepper.tsx:
import { MinusIcon, PlusIcon } from "phosphor-react-native"
import type * as React from "react"
import {
Pressable,
type StyleProp,
StyleSheet,
type TextStyle,
View,
type ViewProps,
type ViewStyle,
} from "react-native"
import * as NumberFieldPrimitive from "@/components/primitives/number-field"
import { resolveStyle } from "@/components/primitives/use-render"
import { Icon } from "@/components/ui/icon"
import {
fontSize,- Update the import paths to match your project.
-
Target iOS 17 or later.
-
Add the Swift package to your app:
.package(url: "https://github.com/phosphor-icons/swift", from: "2.1.0")- Copy the theme files every view uses:
import SwiftUI
import UIKit
struct RGBA: Sendable {
let red: CGFloat
let green: CGFloat
let blue: CGFloat
let alpha: CGFloat
init(_ hex: UInt32, _ alpha: CGFloat = 1) {
red = CGFloat((hex >> 16) & 0xFF) / 255
green = CGFloat((hex >> 8) & 0xFF) / 255
blue = CGFloat(hex & 0xFF) / 255
self.alpha = alpha
}import SwiftUI
extension Color {
public static let surface = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x000000))
public static let surfaceSecondary = Color.adaptive(light: .init(0xF5F5F7), dark: .init(0x161617))
public static let surfaceTertiary = Color.adaptive(light: .init(0xE8E8ED), dark: .init(0x2C2C2E))
public static let surfaceRaised = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x1D1D1F))
public static let label = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
public static let labelSecondary = Color.adaptive(light: .init(0x6E6E73), dark: .init(0xA1A1A6))
public static let labelTertiary = Color.adaptive(light: .init(0x86868B), dark: .init(0x86868B))
public static let labelQuaternary = Color.adaptive(light: .init(0xD2D2D7), dark: .init(0x424245))
public static let control = Color.adaptive(light: .init(0x000000, 0.04), dark: .init(0xFFFFFF, 0.1))
public static let controlPressed = Color.adaptive(light: .init(0x000000, 0.12), dark: .init(0xFFFFFF, 0.22))
public static let controlSelected = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
public static let controlDisabled = Color.adaptive(light: .init(0x000000, 0.03), dark: .init(0xFFFFFF, 0.05))
public static let onControlSelected = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x000000))- Copy the source and every file it uses:
import PhosphorSwift
import SwiftUI
enum StepperMath {
static func canChange(_ value: Double, direction: Int, bounds: ClosedRange<Double>) -> Bool {
direction > 0 ? value < bounds.upperBound : value > bounds.lowerBound
}
static func next(_ value: Double, direction: Int, step: Double, bounds: ClosedRange<Double>) -> Double? {
guard canChange(value, direction: direction, bounds: bounds) else { return nil }
let precision = max(0, -Int(log10(step).rounded(.down)))
let factor = pow(10, Double(precision))
let raw = ((value + Double(direction) * step) * factor).rounded() / factor
return min(max(raw, bounds.lowerBound), bounds.upperBound)
}import PhosphorSwift
import SwiftUI
extension Shadow {
static let control = Shadow(color: .black.opacity(0.08), radius: 0.5, y: 0.5)
static let thumb = Shadow(color: .black.opacity(0.12), radius: 1.5, y: 1)
}
struct SelectionIndicator<Mark: View>: View {
let checked: Bool
let pressed: Bool
let cornerRadius: CGFloat
let mark: Mark
@Environment(\.isEnabled) private var isEnabled
@Environment(\.isInvalid) private var invalidimport SwiftUI
extension EnvironmentValues {
@Entry public var isInvalid = false
@Entry var fieldInset = false
@Entry var fieldGroupInset = false
@Entry var fieldSetInset = false
}
extension View {
public func invalid(_ isInvalid: Bool = true) -> some View {
environment(\.isInvalid, isInvalid)
}
}
public enum FieldOrientation: CaseIterable, Sendable {import SwiftUI
extension EnvironmentValues {
@Entry public var hapticsEnabled = true
}
extension View {
public func haptics(_ enabled: Bool) -> some View {
environment(\.hapticsEnabled, enabled)
}
func hapticFeedback<Trigger: Equatable>(_ feedback: SensoryFeedback, trigger: Trigger) -> some View {
modifier(HapticFeedbackModifier(feedback: feedback, trigger: trigger) { _, _ in true })
}
func hapticFeedback<Trigger: Equatable>(import SwiftUI
public struct Separator: View {
let orientation: Axis
public init(_ orientation: Axis = .horizontal) {
self.orientation = orientation
}
public var body: some View {
Rectangle()
.fill(Color.separator)
.frame(width: orientation == .vertical ? 1 : nil, height: orientation == .horizontal ? 1 : nil)
.frame(maxWidth: orientation == .horizontal ? .infinity : nil, maxHeight: orientation == .vertical ? .infinity : nil)
.accessibilityHidden(true)
}import SwiftUI
public enum TextVariant: CaseIterable, Sendable {
case `default`, h1, h2, h3, h4, p, blockquote, code, lead, large, small, muted
var style: TextStyle {
switch self {
case .h1: .xl3
case .h2: .xl2
case .h3: .xl
case .h4, .lead, .large: .lg
case .code, .small, .muted: .sm
default: .base
}
}- Add the files to your app target.
- Set
minSdkto 24 or higher and add the dependencies:
implementation(platform("androidx.compose:compose-bom:2026.09.00"))
implementation("androidx.compose.foundation:foundation")
implementation("androidx.compose.ui:ui")
implementation("com.adamglin:phosphor-icon-android:1.0.0")- Copy the theme files every view uses:
package com.esuiss.ui.theme
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.Immutable
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.dropShadow
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.graphics.shadow.Shadow as DropShadow
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.style.LineHeightStyle
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.DpOffsetpackage com.esuiss.ui.theme
import androidx.compose.runtime.Immutable
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
@Immutable
data class Colors(
val surface: Color,
val surfaceSecondary: Color,
val surfaceTertiary: Color,
val surfaceRaised: Color,
val label: Color,
val labelSecondary: Color,
val labelTertiary: Color,
val labelQuaternary: Color,- Copy the source and every file it uses:
package com.esuiss.ui.interactions
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.awaitEachGesture
import androidx.compose.foundation.gestures.awaitFirstDown
import androidx.compose.foundation.gestures.waitForUpOrCancellation
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.interaction.collectIsFocusedAsState
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.RowScope
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.widthpackage com.esuiss.ui.components
import androidx.compose.runtime.compositionLocalOf
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
val LocalContentStyle = compositionLocalOf { TextStyle.Default }
val LocalContentColor = compositionLocalOf { Color.Unspecified }
val LocalIconSize = compositionLocalOf { 20.dp }package com.esuiss.ui.components
import android.provider.Settings
import androidx.compose.animation.core.CubicBezierEasing
import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.gestures.Orientation
import androidx.compose.foundation.text.selection.TextSelectionColors
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.draw.drawWithContent
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.geometry.Sizepackage com.esuiss.ui.components
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.remember
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.compose.ui.hapticfeedback.HapticFeedback
import androidx.compose.ui.hapticfeedback.HapticFeedbackType
import androidx.compose.ui.platform.LocalHapticFeedback
val LocalHapticsEnabled = staticCompositionLocalOf { true }
@Composable
fun ProvideHaptics(enabled: Boolean, content: @Composable () -> Unit) {
CompositionLocalProvider(LocalHapticsEnabled provides enabled, content = content)
}package com.esuiss.ui.components
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.ColorFilter
import androidx.compose.ui.graphics.takeOrElse
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.unit.Dp
import com.esuiss.ui.theme.EsuissTheme
@Composable
fun Icon(
imageVector: ImageVector,- Update the
com.esuiss.uipackage names to match your project.
Usage
import { Stepper, StepperInput, StepperGroup, StepperDecrement, StepperIncrement, StepperSeparator } from "@/components/interactions/stepper"<Stepper defaultValue={1} min={0} max={10}>
<StepperInput accessibilityLabel="Quantity" />
<StepperGroup>
<StepperDecrement />
<StepperSeparator />
<StepperIncrement />
</StepperGroup>
</Stepper>Compose StepperInput and a StepperGroup containing StepperDecrement, StepperSeparator and StepperIncrement inside Stepper.
Use it uncontrolled with defaultValue (0 by default) or controlled with value and onValueChange. Clearing the field never reports null; the change is cancelled instead. min, max, step, format (Intl.NumberFormatOptions), locale and disabled are passed to the number field.
Examples
A print settings list with copies, a percentage scale stepping by 5, and a disabled row.


import * as React from "react"
import { View } from "react-native"
import { Stepper, StepperDecrement, StepperGroup, StepperIncrement, StepperInput, StepperSeparator } from "@/components/interactions/stepper"
import { Text } from "@/components/ui/text"
function StepperRow({
label,
...props
}: React.ComponentProps<typeof Stepper> & { label: string }) {
const labelId = React.useId()
return (
<View className="min-h-11 flex-row items-center justify-between gap-4 px-4 py-1.5">
<Text nativeID={labelId} className="text-base">
{label}
</Text>
<Stepper {...props}>
<StepperInput accessibilityLabelledBy={labelId} />
<StepperGroup>
<StepperDecrement />
<StepperSeparator />
<StepperIncrement />
</StepperGroup>
</Stepper>
</View>
)
}
function PrintExample() {
const [copies, setCopies] = React.useState(1)
const [scale, setScale] = React.useState(100)
return (
<View className="w-full gap-3">
<View className="overflow-hidden rounded-2xl border border-separator">
<StepperRow
label="Copies"
value={copies}
onValueChange={setCopies}
min={1}
max={999}
/>
<View className="h-px bg-separator" />
<StepperRow
label="Scale"
value={scale}
onValueChange={setScale}
min={25}
max={400}
step={5}
format={{ style: "unit", unit: "percent" }}
/>
<View className="h-px bg-separator" />
<StepperRow label="Pages per sheet" defaultValue={1} disabled />
</View>
<Text
accessibilityLiveRegion="polite"
className="text-sm text-label-secondary"
>
{copies} {copies === 1 ? "copy" : "copies"} at {scale}%
</Text>
</View>
)
}
export function StepperPrintExample() {
return (
<PrintExample />
)
}import EsuissUI
import SwiftUI
struct StepperParts: View {
var body: some View {
StepperInput()
StepperGroup {
StepperDecrement()
StepperSeparator()
StepperIncrement()
}
}
}
struct StepperRow<Content: View>: View {
let label: LocalizedStringKey
@ViewBuilder let content: () -> Content
var body: some View {
HStack(spacing: 16) {
Text(label)
.textStyle(.base)
.foregroundStyle(Color.label)
.frame(maxWidth: .infinity, alignment: .leading)
content()
.accessibilityLabel(Text(label))
}
.padding(.horizontal, 16)
.padding(.vertical, 6)
.frame(minHeight: 44)
}
}
struct StepperPrint: View {
@State private var copies = 1
@State private var scale = 100.0
@State private var pages = 1
var body: some View {
let shape = RoundedRectangle(cornerRadius: Radius.xl2, style: .continuous)
VStack(alignment: .leading, spacing: 12) {
VStack(spacing: 0) {
StepperRow(label: "Copies") {
ValueStepper(value: $copies, in: 1...999) { StepperParts() }
}
Color.separator.frame(height: 1)
StepperRow(label: "Scale") {
ValueStepper(
value: $scale,
in: 25...400,
step: 5,
format: FloatingPointFormatStyle<Double>.Percent().scale(1)
) { StepperParts() }
}
Color.separator.frame(height: 1)
StepperRow(label: "Pages per sheet") {
ValueStepper(value: $pages) { StepperParts() }
.disabled(true)
}
}
.clipShape(shape)
.overlay { shape.strokeBorder(Color.separator) }
Text(verbatim: "\(copies) \(copies == 1 ? "copy" : "copies") at \(Int(scale))%")
.textStyle(.sm)
.foregroundStyle(Color.labelSecondary)
.accessibilityAddTraits(.updatesFrequently)
}
}
}import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.heightIn
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableDoubleStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.semantics.LiveRegionMode
import androidx.compose.ui.semantics.liveRegion
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.unit.dp
import com.esuiss.ui.components.Text
import com.esuiss.ui.interactions.Stepper
import com.esuiss.ui.interactions.StepperDecrement
import com.esuiss.ui.interactions.StepperGroup
import com.esuiss.ui.interactions.StepperIncrement
import com.esuiss.ui.interactions.StepperInput
import com.esuiss.ui.interactions.StepperSeparator
import com.esuiss.ui.theme.EsuissTheme
import com.esuiss.ui.theme.Radius
import com.esuiss.ui.theme.Typography
import java.text.DecimalFormat
import java.text.NumberFormat
@Composable
fun StepperControls() {
StepperGroup {
StepperDecrement()
StepperSeparator()
StepperIncrement()
}
}
@Composable
fun StepperRow(
label: String,
value: Double,
onValueChange: (Double) -> Unit,
min: Double = Double.NEGATIVE_INFINITY,
max: Double = Double.POSITIVE_INFINITY,
step: Double = 1.0,
enabled: Boolean = true,
format: NumberFormat = remember { NumberFormat.getNumberInstance() },
) {
Row(
modifier = Modifier
.fillMaxWidth()
.heightIn(min = 44.dp)
.padding(horizontal = 16.dp, vertical = 6.dp),
horizontalArrangement = Arrangement.spacedBy(16.dp),
verticalAlignment = Alignment.CenterVertically,
) {
Text(label, modifier = Modifier.weight(1f), style = Typography.base)
Stepper(value = value, onValueChange = onValueChange, min = min, max = max, step = step, enabled = enabled, format = format) {
StepperInput(contentDescription = label)
StepperControls()
}
}
}
@Composable
fun StepperPrint() {
val colors = EsuissTheme.colors
var copies by rememberSaveable { mutableDoubleStateOf(1.0) }
var scale by rememberSaveable { mutableDoubleStateOf(100.0) }
var pages by rememberSaveable { mutableDoubleStateOf(1.0) }
val percent = remember { DecimalFormat("0'%'") }
val shape = RoundedCornerShape(Radius.xl2)
Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
Column(
Modifier
.fillMaxWidth()
.clip(shape)
.border(1.dp, colors.separator, shape),
) {
StepperRow("Copies", copies, { copies = it }, min = 1.0, max = 999.0)
Box(Modifier.fillMaxWidth().height(1.dp).background(colors.separator))
StepperRow("Scale", scale, { scale = it }, min = 25.0, max = 400.0, step = 5.0, format = percent)
Box(Modifier.fillMaxWidth().height(1.dp).background(colors.separator))
StepperRow("Pages per sheet", pages, { pages = it }, enabled = false)
}
Text(
"${copies.toInt()} ${if (copies == 1.0) "copy" else "copies"} at ${scale.toInt()}%",
modifier = Modifier.semantics { liveRegion = LiveRegionMode.Polite },
style = Typography.sm.copy(color = colors.labelSecondary),
)
}
}API Reference
Stepper
The root that holds the value and limits.
React.ComponentProps<typeof NumberFieldPrimitive.Root>- About
- The current value when controlled.
- Type
number- Default
- —
- About
- The initial value when uncontrolled. Defaults to
0. - Type
number- Default
- 0
- About
- Called with the new number and change details.
- Type
( value: number, eventDetails: NumberFieldPrimitive.ChangeEventDetails ) => void- Default
- —
StepperInput
The editable, right-aligned value.
React.ComponentProps<typeof NumberFieldPrimitive.Input>StepperGroup
The rounded field that holds the buttons.
React.ComponentProps<typeof NumberFieldPrimitive.Group>StepperDecrement
The minus button.
React.ComponentProps<typeof NumberFieldPrimitive.Decrement>StepperIncrement
The plus button.
React.ComponentProps<typeof NumberFieldPrimitive.Increment>StepperSeparator
A thin divider between the buttons.
ViewPropsAccessibility
- The minus and plus buttons have the
buttonrole. - Label the value with
accessibilityLabeloraccessibilityLabelledByonStepperInput. - The separator is hidden from screen readers.
Notes
- A selection haptic plays on each step, if the app provides an adapter through
HapticsProvider. - The group uses
bg-control. Buttons usebg-surface-raisedwith a small shadow (bg-label-quaternaryin dark mode) andbg-control-pressedwhen pressed; a disabled button or one at its limit usesbg-control-disabledwith atext-label-quaternaryicon. - Disabled text uses
text-label-quaternary.