# rn-stepper
URL: /docs/native/docyrus/stepper

Compound step indicator for multi-step wizards and onboarding flows — six variants, per-step status, non-linear navigation and animated connectors.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-stepper
```

**Dependencies:**
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-svg](https://www.npmjs.com/package/react-native-svg)
- [tailwind-variants](https://www.npmjs.com/package/tailwind-variants)
- [expo-linear-gradient (optional)](https://www.npmjs.com/package/expo-linear-gradient)

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

```tsx
import { Step, Stepper } from '@/components/docyrus-native/stepper';

```

### Steps array

The `steps` prop is a native convenience that maps onto `
```

### Vertical with content

In vertical orientation a step's `children` render beside the connector below it.

```tsx

  
  
  

```

### Custom connector

```tsx
}>
  ...

```

## 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` | `` | 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` |