Docyrus
Stepper
Compound step indicator for multi-step wizards and onboarding flows — six variants, per-step status, non-linear navigation and animated connectors.
iOSAndroid
Installation
pnpm dlx @docyrus/cli add @docyrus/rn-stepperRequired Packages(4 packages)
pnpm add react-native-reanimated react-native-svg tailwind-variants expo-linear-gradient (optional)The API mirrors the web Stepper 1:1 (Stepper + Step + StepConnector, same contexts and hooks). expo-linear-gradient is an optional peer: when it is installed the gradient variant renders a shimmering sweep on the active step, otherwise it falls back to a solid primary fill.
Usage
import { Step, Stepper } from '@/components/docyrus-native/stepper';
<Stepper activeStep={1}>
<Step label="Account" description="Create your account" icon="fal user" />
<Step label="Profile" description="Set up your profile" />
<Step label="Billing" optional />
<Step label="Complete" />
</Stepper>Steps array
The steps prop is a native convenience that maps onto <Step> children:
<Stepper
steps={[
{ label: 'Account', description: 'Create your account' },
{ label: 'Profile', status: 'error', description: 'Missing avatar' },
{ label: 'Complete' }
]}
activeStep={1}
variant="outline"
alternativeLabel
/>Non-linear navigation
const [active, setActive] = useState(0);
<Stepper activeStep={active} nonLinear onStepClick={setActive}>
<Step label="Details" />
<Step label="Members" />
<Step label="Locked" disabled />
</Stepper>Vertical with content
In vertical orientation a step's children render beside the connector below it.
<Stepper activeStep={1} orientation="vertical">
<Step label="Upload file" description="CSV or XLSX">
<Text>contacts.csv — 1,204 rows</Text>
</Step>
<Step label="Map columns" />
<Step label="Import" />
</Stepper>Custom connector
<Stepper activeStep={1} variant="dashed" connector={<StepConnector animated={false} />}>
...
</Stepper>Variants
| Variant | Description |
|---|---|
default | Filled circles (muted → primary), check on finished steps, pulsing ring on the active step |
outline | Bordered circles; finished steps fill with primary |
dots | Small dots with the label underneath; the active dot springs to 1.2× and pulses |
dashed | Dashed border on waiting steps and dashed connectors |
gradient | Filled circles with a shimmering gradient sweep on the active step (expo-linear-gradient, solid fallback) |
minimal | No circles — inline check / error glyph next to the label and an underline under the active step |
Sizes
| Size | Indicator | Glyph |
|---|---|---|
sm | 24px | 12px |
default | 32px | 16px |
lg | 40px | 20px |
md is still accepted as an alias of default.
API Reference
Stepper
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | <Step> elements (fragments are flattened). Ignored when steps is provided |
steps | StepItem[] | — | Native convenience — array alternative to <Step> children |
activeStep | number | 0 | Index of the active step. Steps before it are finish, it is process, steps after are wait |
currentStep | number | — | Deprecated alias of activeStep |
variant | 'default' | 'outline' | 'dots' | 'dashed' | 'gradient' | 'minimal' | 'default' | Visual style |
size | 'sm' | 'default' | 'lg' | 'md' | 'default' | Indicator and text size (md = default) |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Layout direction |
nonLinear | boolean | false | Makes non-disabled steps pressable (requires onStepClick) |
onStepClick | (index: number) => void | — | Called with the pressed step index when nonLinear |
alternativeLabel | boolean | false | Horizontal only — puts labels under the indicators (always on for dots) |
connector | ReactNode | <StepConnector /> | Custom connector element rendered between steps |
scrollable | boolean | true | Horizontal only — wraps the steps in a horizontal ScrollView so long steppers scroll instead of squeezing, and scrolls the active step into view |
className | string | — | Root classes |
labelClassName | string | — | Extra classes for every step label |
descriptionClassName | string | — | Extra classes for every step description |
ref | Ref<View> | — | Root view ref |
Also accepts every ViewProps prop.
Step
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | — | Step label (strings are wrapped in Text) |
description | ReactNode | — | Secondary text under the label |
icon | ReactNode | string | — | Replaces the number / check / error glyph. A string renders a DocyrusIcon (e.g. "fal user") tinted for the status |
status | 'wait' | 'process' | 'finish' | 'error' | derived | Overrides the status derived from activeStep |
optional | boolean | false | Shows an "Optional" caption (ui.stepper.optional) |
disabled | boolean | false | Excludes the step from nonLinear navigation and dims it |
children | ReactNode | — | Vertical only — content rendered beside the connector below the step |
className | string | — | Step container classes |
labelClassName | string | — | Label classes (merged after the Stepper-level one) |
descriptionClassName | string | — | Description classes |
ref | Ref<View> | — | Step view ref |
Also accepts every ViewProps prop.
StepConnector
| Prop | Type | Default | Description |
|---|---|---|---|
animated | boolean | true | Animates the completion fill (400 ms, reanimated). When false the fill snaps |
className | string | — | Connector track classes |
ref | Ref<View> | — | Connector view ref |
The completed state is read from StepConnectorCompletedContext (set by Stepper for each gap).
StepItem
| Property | Type | Description |
|---|---|---|
key | string | Stable React key (defaults to step-<index>) |
label | ReactNode | Step label |
description | ReactNode | Secondary text |
icon | ReactNode | string | Custom glyph (string → DocyrusIcon) |
status | StepStatus | Status override |
optional | boolean | Shows the "Optional" caption |
disabled | boolean | Not pressable in nonLinear mode |
content | ReactNode | Vertical only — rendered beside the connector (the Step children) |
StepperContextValue
| Field | Type | Description |
|---|---|---|
activeStep | number | Resolved active step |
orientation | StepperOrientation | Layout direction |
variant | StepperVariant | Visual style |
size | StepperSize | Normalized size (md → default) |
nonLinear | boolean | Whether steps are pressable |
alternativeLabel | boolean | Labels under indicators |
onStepClick | (index: number) => void | Step press handler |
totalSteps | number | Number of steps |
labelClassName | string | Native-only — Stepper-level label classes |
descriptionClassName | string | Native-only — Stepper-level description classes |
Components
| Component | Description |
|---|---|
Stepper | Root — lays out steps and connectors, provides the contexts |
Step | A single step (indicator + label + description) |
StepConnector | Line between two steps with an animated completion fill |
Hooks & Contexts
| Export | Description |
|---|---|
useStepperContext() | Reads StepperContextValue (throws outside <Stepper>) |
useStepIndex() | Index of the enclosing step |
useStepConnectorCompleted() | Whether the enclosing connector's previous step is finished |
StepperContext | Context carrying StepperContextValue |
StepIndexContext | Context carrying the step index |
StepConnectorCompletedContext | Context carrying the connector completed flag |
stepperVariants | tv() root variants (variant, size, orientation) |
Translations
| Key | English fallback |
|---|---|
ui.stepper.progress | Progress (root accessibility label) |
ui.stepper.optional | Optional |
Type Exports
| Type | Description |
|---|---|
StepperProps | Props for Stepper |
StepProps | Props for Step |
StepConnectorProps | Props for StepConnector |
StepItem | Entry of the steps array prop |
StepStatus | 'wait' | 'process' | 'finish' | 'error' |
StepperVariant | 'default' | 'outline' | 'dots' | 'dashed' | 'gradient' | 'minimal' |
StepperSize | 'sm' | 'default' | 'lg' |
StepperOrientation | 'horizontal' | 'vertical' |
StepperContextValue | Value of StepperContext |
StatusChip
A reusable tone-based chip for status, priority, and other compact enum labels.
TeamChatChannel
Team chat channel feed for React Native with an inverted list, day separators, an unread marker, a keyboard-docked composer with @ mentions, emoji, attachments and entity links, long-press reactions and thread sheets.