# Stepper

> Shows the steps of a flow and the step you are on.

A stepper shows the steps of a flow, which ones are done, and the one people are on, such as applying for a clearance.

## When to use

- Use it for flows of 3 to 6 steps that people go through in order.
- Name each step with a short noun: "Data rilis", "Dokumen".
- Save a draft at every step, so people can stop and come back: "Simpan dulu, lanjutkan kapan saja."
- Use one page with sections instead when the form is short.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/stepper/_

## Anatomy

1. Done step
2. Current step
3. Upcoming step
4. Connector

An ordered list of steps. Each step is a 32px circle and its name below it, joined to the next step by a 1px line.

| State | Circle | Line to the next step |
| --- | --- | --- |
| Completed | `primary-soft` with a check, in `primary-text` | `primary` |
| Current | `primary` with the number, in `primary-foreground` | `border` |
| Next | `muted` with the number, in `muted-foreground` | `border` |

Below `sm` only the current step's name shows, with a line such as "Langkah 2 dari 4" under the stepper; screen readers still hear every name.

## Variants

There is one style, horizontal.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `value` | `v-model` | built from `Row` (no stepper in `shadcn_ui`) | number | none (React), `1` (Vue) | The current step, from 1. |
| `completedText` | `completed-text` | `Semantics label` | text | `completed` | Read after each completed step, such as "selesai". |
| `StepperItem step` | `StepperItem :step` | the index | number | none | The step's number. |
| `StepperTitle`, `StepperDescription` | same | `Text` | text | none | The step's name and an optional line. |

## Code

**React**
```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Stepper, StepperIndicator, StepperItem, StepperSeparator, StepperTitle } from "@/components/ui/stepper"

const steps = ["Pilih lagu", "Data rilis", "Dokumen", "Kirim"]

export default function StepperDemo() {
  const [step, setStep] = useState(2)
  return (
    <div className="grid w-full max-w-xl gap-6">
      <Stepper value={step} completedText="selesai" aria-label="Ajukan clearance">
        {steps.map((title, index) => (
          <StepperItem key={title} step={index + 1}>
            <StepperIndicator />
            <StepperTitle>{title}</StepperTitle>
            {index < steps.length - 1 && <StepperSeparator />}
          </StepperItem>
        ))}
      </Stepper>
      <p className="text-center text-sm text-muted-foreground sm:hidden">
        Langkah {step} dari {steps.length}
      </p>
      <div className="flex justify-between">
        <Button variant="outline" disabled={step === 1} onClick={() => setStep((s) => s - 1)}>
          Kembali
        </Button>
        <Button disabled={step === steps.length} onClick={() => setStep((s) => s + 1)}>
          Lanjut
        </Button>
      </div>
    </div>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { ref } from "vue"
import { Button } from "@/components/ui/button"
import { Stepper, StepperIndicator, StepperItem, StepperSeparator, StepperTitle } from "@/components/ui/stepper"

const steps = ["Pilih lagu", "Data rilis", "Dokumen", "Kirim"]
const step = ref(2)
</script>

<template>
  <div class="grid w-full max-w-xl gap-6">
    <Stepper v-model="step" completed-text="selesai" aria-label="Ajukan clearance">
      <StepperItem v-for="(title, index) in steps" :key="title" :step="index + 1">
        <StepperIndicator />
        <StepperTitle>{{ title }}</StepperTitle>
        <StepperSeparator v-if="index < steps.length - 1" />
      </StepperItem>
    </Stepper>
    <p class="text-center text-sm text-muted-foreground sm:hidden">Langkah {{ step }} dari {{ steps.length }}</p>
    <div class="flex justify-between">
      <Button variant="outline" :disabled="step === 1" @click="step--">Kembali</Button>
      <Button :disabled="step === steps.length" @click="step++">Lanjut</Button>
    </div>
  </div>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';
import 'package:sosialoka_ui/sosialoka_ui.dart';

const clearanceSteps = ['Pilih lagu', 'Data rilis', 'Dokumen', 'Kirim'];

// shadcn_ui has no stepper: circles joined by lines, drawn from the theme. On phones only the current
// step's name shows, with "Langkah 2 dari 4" under the steps; every name stays in the semantics.
class StepperDemo extends StatefulWidget {
  const StepperDemo({super.key});

  @override
  State<StepperDemo> createState() => _StepperDemoState();
}

class _StepperDemoState extends State<StepperDemo> {
  int step = 2;

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    final c = context.sosialoka;
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 576),
      child: LayoutBuilder(
        builder: (context, constraints) {
          final compact = constraints.maxWidth < 640;
          return Column(
            mainAxisSize: MainAxisSize.min,
            spacing: 16,
            children: [
              Row(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  for (var i = 0; i < clearanceSteps.length; i++)
                    Expanded(
                      child: Semantics(
                        label: '${clearanceSteps[i]}${i + 1 < step ? ', selesai' : ''}',
                        selected: i + 1 == step,
                        child: ExcludeSemantics(
                          child: Stack(
                            children: [
                              // The line to the next step: primary once this step is done.
                              if (i < clearanceSteps.length - 1)
                                Positioned(
                                  top: 15.5,
                                  left: 0,
                                  right: 0,
                                  child: FractionalTranslation(
                                    translation: const Offset(0.5, 0),
                                    child: Padding(
                                      padding: const EdgeInsets.symmetric(horizontal: 24),
                                      child: Container(height: 1, color: i + 1 < step ? theme.colorScheme.primary : theme.colorScheme.border),
                                    ),
                                  ),
                                ),
                              Column(
                                children: [
                                  Container(
                                    width: 32,
                                    height: 32,
                                    alignment: Alignment.center,
                                    decoration: BoxDecoration(
                                      shape: BoxShape.circle,
                                      color: i + 1 < step
                                          ? c.primarySoft
                                          : i + 1 == step
                                              ? theme.colorScheme.primary
                                              : theme.colorScheme.muted,
                                    ),
                                    child: i + 1 < step
                                        ? Icon(LucideIcons.check, size: 16, color: c.primaryText)
                                        : Text(
                                            '${i + 1}',
                                            style: theme.textTheme.small.copyWith(
                                              color: i + 1 == step ? theme.colorScheme.primaryForeground : theme.colorScheme.mutedForeground,
                                            ),
                                          ),
                                  ),
                                  if (!compact || i + 1 == step) ...[
                                    const SizedBox(height: 8),
                                    Text(
                                      clearanceSteps[i],
                                      textAlign: TextAlign.center,
                                      style: i + 1 == step ? theme.textTheme.small : theme.textTheme.muted,
                                    ),
                                  ],
                                ],
                              ),
                            ],
                          ),
                        ),
                      ),
                    ),
                ],
              ),
              if (compact) Text('Langkah $step dari ${clearanceSteps.length}', style: theme.textTheme.muted),
              Row(
                mainAxisAlignment: MainAxisAlignment.spaceBetween,
                children: [
                  ShadButton.outline(enabled: step > 1, onPressed: () => setState(() => step--), child: const Text('Kembali')),
                  ShadButton(enabled: step < clearanceSteps.length, onPressed: () => setState(() => step++), child: const Text('Lanjut')),
                ],
              ),
            ],
          );
        },
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/stepper.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/stepper.json
```

## Accessibility

- It is an ordered list; the current step has `aria-current="step"`.
- Completed steps say so to screen readers, such as "selesai".
- Give the list a name with `aria-label`, such as "Ajukan clearance".
- The circles and lines are decoration; the names carry the meaning.
