React Stepper: Zustände, Varianten und Smartphones

Ein React Stepper beantwortet eine Frage auf einen Blick: Wie weit bin ich, und was fehlt noch? Checkouts, Onboarding-Flows, Identitätsprüfungen (KYC) und lange Einstellungsformulare nutzen alle einen. Schwierig sind drei Dinge: die Zustände (wie sieht ein fehlgeschlagener oder ladender Schritt aus?), das Layout (fünf Schritte mit Titeln passen nicht aufs Handy) und die Barrierefreiheit (eine Reihe Kreise sagt einem Screenreader ohne das richtige Markup nichts). Dieser Guide geht jeden Punkt mit der Steps-Komponente von Wingo UI durch, der Bibliothek, die wir bauen, und vergleicht sie mit den wichtigsten Alternativen. Sitzt der Stepper über einem Formular, behandelt das Tutorial zum React Multi Step Form Validierung, gespeicherte Entwürfe und Übergänge.

Wann solltest du einen Stepper verwenden?

Nimm einen, wenn die Aufgabe eine feste Reihenfolge hat, drei bis sieben Schritte und ein klares Ende. Jeder Schritt sollte vom vorherigen abhängen oder sich in dieser Reihenfolge zumindest besser lesen: Versand vor Zahlung, Ausweis vor Adressnachweis.

In zwei Fällen lässt du ihn weg. Sind die Abschnitte unabhängig und springen die Leute frei zwischen ihnen hin und her, nimm Tabs; ein Stepper suggeriert eine Reihenfolge, die es nicht gibt. Gibt es nur einen langen Schritt, reicht ein einfacher Progress-Balken.

Welche Stepper-Variante passt zu welchem Flow?

Nummerierte Kreise passen zu Formularen, Balken zum Checkout und Punkte zum Onboarding. In Steps wählst du sie mit variant:

Zwei Layout-Props regeln die Anordnung. orientation="vertical" stapelt die Schritte in einer Spalte, mit Beschreibungen neben den Markern. Ein vertikaler Stepper passt zu KYC und Kontoeröffnung, wo jeder Schritt eine Zeile Erklärung braucht („Kontoauszug oder Nebenkostenabrechnung“), und er funktioniert bei jeder Breite. labelPlacement="end" setzt horizontale Titel neben die Marker statt darunter.

Dazu kommen die visuellen Props, die alle Komponenten von Wingo UI gemeinsam haben: size (sm, md, lg: Marker mit 24, 28 oder 32px), tone (standardmäßig neutral, sonst brand, success, warning, danger, info), color für jede CSS-Farbe und connector="dashed", um die Verbindungslinien zu den noch ausstehenden Schritten gestrichelt zu zeichnen.

npx wingo-ui@latest add steps

Was bedeutet jeder Schrittzustand?

Jeder Schritt hat einen von fünf Zuständen. Drei leitet Steps aus dem aktuellen value ab: Schritte davor sind erledigt, der Schritt bei value ist aktuell, die danach stehen aus. Die anderen zwei sind immer explizit und werden mit status am Schritt gesetzt:

Fehler und Laden sind explizit, weil nur dein Code sie kennt. Ein KYC-Flow ist das klarste Beispiel: Die Identitätsprüfung läuft auf einem Server, kann Sekunden dauern und kann aus einem Grund scheitern, den die Person selbst beheben kann.

"use client";

import { useState } from "react";
import { Steps, type StepItem } from "@/components/ui/steps";
import { Button } from "@/components/ui/button";

type Check = "idle" | "checking" | "failed" | "passed";

export function IdentityVerification({ verify }: { verify: () => Promise<boolean> }) {
  const [check, setCheck] = useState<Check>("idle");

  const steps: StepItem[] = [
    { id: "personal", title: "Persönliche Daten", description: "Emma Carter" },
    {
      id: "identity",
      title: "Identitätsprüfung",
      description:
        check === "failed" ? "Das Foto ist unscharf. Nimm es noch einmal auf." : check === "checking" ? "Dein Ausweis wird geprüft" : "Führerschein oder Reisepass",
      status: check === "checking" ? "loading" : check === "failed" ? "error" : undefined,
    },
    { id: "address", title: "Adressnachweis", description: "Kontoauszug oder Nebenkostenabrechnung" },
    { id: "done", title: "Fertig" },
  ];

  const send = async () => {
    setCheck("checking");
    setCheck((await verify().catch(() => false)) ? "passed" : "failed");
  };

  return (
    <div className="flex flex-col gap-5">
      <Steps steps={steps} value={check === "passed" ? "address" : "identity"} orientation="vertical" clickable="none" />
      {check !== "passed" && (
        <Button loading={check === "checking"} loadingText="Wird geprüft" onClick={send}>
          {check === "failed" ? "Foto erneut hochladen" : "Foto senden"}
        </Button>
      )}
    </div>
  );
}

Schreib den Grund für einen Fehler in die description des Schritts, wie oben. Ein rotes „!“ sagt den Leuten, dass etwas nicht stimmt; der Text sagt ihnen, was sie tun sollen. optional: true zeigt einen Hinweis „Optional“ unter dem Titel (bei Punkten, die keinen sichtbaren Titel haben, nur für Screenreader), und disabled: true sorgt dafür, dass ein Schritt nie klickbar wird.

Welche Schritte sollten klickbar sein?

clickable entscheidet, welche Schritte Buttons sind. Der Standard "completed" macht erledigte Schritte, den aktuellen und fehlerhafte klickbar. Das deckt den häufigen Fall „zurück und die Adresse korrigieren“ ab, ohne dass jemand nach vorn springen kann. "all" macht jeden aktivierten Schritt zum Button, für Flows, in denen die Reihenfolge nur ein Vorschlag ist. "none" macht den Stepper zur reinen Anzeige, wie im KYC-Beispiel, wo nur der Server dich weiterbringt.

Klicks rufen onValueChange(id, step) auf. Ein Checkout Stepper verteilt sich meist auf mehrere Routen, also ist die URL maßgeblich: Gib jedem Schritt ein href und übergib die Link-Komponente deines Routers. Steps rendert klickbare Schritte als Links, und der aktuelle bekommt aria-current="step":

"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import { Steps, type StepItem } from "@/components/ui/steps";

const CHECKOUT: StepItem[] = [
  { id: "cart", title: "Warenkorb", href: "/checkout/cart" },
  { id: "shipping", title: "Versand", href: "/checkout/shipping" },
  { id: "payment", title: "Zahlung", href: "/checkout/payment" },
  { id: "review", title: "Prüfen", href: "/checkout/review" },
];

export function CheckoutProgress() {
  const pathname = usePathname();
  const current = CHECKOUT.find((step) => step.href === pathname)?.id ?? "cart";
  return <Steps steps={CHECKOUT} value={current} variant="bars" linkComponent={Link} />;
}

Mit dem Standardwert von clickable bleiben die ausstehenden Schritte reiner Text, also landet niemand mit leerem Warenkorb auf der Zahlungsseite. Sichere die Routen trotzdem auch auf dem Server ab; ein Stepper ist keine Zugriffskontrolle.

Ein Stolperstein: Der Vergleich von usePathname() mit href geht schief, sobald der Pfad ein Locale-Präfix oder einen abschließenden Slash enthält. Rendert der Stepper aus app/checkout/layout.tsx, liefert useSelectedLayoutSegment() aus next/navigation direkt "shipping", und du kannst stattdessen mit der id des Schritts vergleichen.

Wie passt ein Stepper aufs Handy?

Unter 640px wird ein horizontaler Stepper mit Kreisen oder Balken zu einem kompakten Header: „Step 2 of 4“ in kleiner Schrift, der aktuelle Titel, „Next: Payment“ rechts und ein dünner Fortschrittsbalken darunter. Beide Layouts stehen im HTML, und ein CSS-Breakpoint wählt eins aus. So ist schon das Server-Rendering auf dem Handy richtig, und nach der Hydration verschiebt sich nichts. mobileVariant="same" behält den vollen Stepper auf Handys, und compact zeigt den kompakten Header bei jeder Breite, etwa für eine schmale Card oder ein Sheet.

Vertikale Stepper und Punkte behalten ihr Layout bei jeder Größe, denn beide passen schon auf einen schmalen Screen. Ist eine horizontale Liste breiter als ihr Container und hast du den kompakten Header abgeschaltet, scrollt sie seitwärts und hält den aktuellen Schritt sichtbar.

Auf Touchscreens bekommen klickbare Marker und Punkte eine Trefferfläche von 44px, das Minimum, das wir für jedes Control nutzen. Die Begründung steht in unserem Beitrag zur Größe von Touch Targets.

Wie machst du einen Stepper barrierefrei?

Nutze eine geordnete Liste, markier den aktuellen Schritt mit aria-current="step", schreib den Zustand jedes Schritts in Worten aus und unterstütze die Pfeiltasten. In Steps sieht das Markup so aus:

• Eine geordnete Liste. Steps rendert ein <ol> mit dem Namen „Progress“ (labels.progress), also sagt ein Screenreader eine Liste mit vier Einträgen und die Position jedes Eintrags an.
• aria-current="step" auf dem aktuellen Schritt, der Attributwert, den die ARIA-Spezifikation genau für diesen Fall definiert.
• Zustand in Worten. Der zugängliche Name jedes Schritts enthält seinen Zustand („Shipping, Completed“), denn Farbe und ein Häkchen-Icon sind für einen Screenreader unsichtbar.
• Tastatur. Tab erreicht jeden klickbaren Schritt; die Pfeiltasten links und rechts (bei vertikaler Ausrichtung hoch und runter) wechseln zwischen ihnen, Pos1 und Ende springen an die Enden.
• Der kompakte Header ist eine progressbar mit aria-valuenow und „Step 2 of 4“ als Textwert.

Alle diese Texte stecken in labels, eine Übersetzung oder ein anderer Tonfall braucht also nur ein Prop.

Was ist mit einem kompletten Checkout Stepper in React?

Brauchst du einen kompletten Checkout statt nur der Anzeige, setzt der Block Checkout Steps vier Schritte (Lieferdaten, Versand, Zahlung und Prüfen) neben eine Sticky-Bestellübersicht. Er validiert jeden Schritt, zeigt Paketstationen und Abholpunkte, rechnet Zahlungsgebühren in die Summe ein und macht auf dem Handy aus jedem Schritt eine Seite in voller Höhe, mit Summe und Continue-Button über dem Home-Indikator. Sein Header nutzt den Stepper aus Form Wizard, "horizontal" oder "progress".

Achte auf seine Standardwerte: Er wurde für den rumänischen Markt gebaut, also ist country auf "RO" gesetzt (Prüfung von Postleitzahl und Unternehmens-Steuernummer), currency auf "RON", und der Company-Schalter fragt nach einer CUI. Setz für andere Märkte country, currency und invoice={false}.

Wie schneidet Steps im Vergleich zu MUI und shadcn ab?

MUI liefert einen ausgereiften Stepper in Material UI, shadcn/ui hat keinen, und Wingo UI Steps ist der mit eingebautem Handy-Header sowie Fehler- und Ladezuständen. Die Details, Stand Oktober 2026 (Doku von Material UI v9.5):

Quellen: MUI Stepper Doku (opens in a new tab), Komponentenliste von shadcn/ui (opens in a new tab), ReUI Stepper Doku (opens in a new tab).

MUI ist die bessere Wahl, wenn deine App schon Material UI nutzt: Der Stepper fügt sich in das übrige Design System ein, und laut der MUI-Doku (opens in a new tab) sind vertikale Stepper für schmale Bildschirme gedacht. Willst du einen shadcn Stepper, der sich mit der shadcn CLI installieren lässt, passt die komponierbare API von ReUI (Stepper, StepperItem, StepperIndicator) zu diesem Stil. Wingo UI Steps passt, wenn ein Tailwind Stepper die Zustände, den Handy-Header und die Tastaturbedienung schon fertig mitbringen soll.

Wo fängst du am besten an?

Fang mit der Steps-Doku an: Playground und Beispiele für vertikale Schritte mit Icons, einen Flow mit Laden und Fehler, Balken, Punkte, verlinkte Schritte und den Handy-Header. Steps, Checkout Steps und Form Wizard gehören zu Wingo UI Pro: $8 im Monat, $80 im Jahr oder $150 einmalig, Stand Oktober 2026 (Preise). Weitere Guides wie dieser stehen in der Kategorie Komponenten-Guides, angefangen mit dem Guide zu React-Formularkomponenten.

Häufige Fragen

Was ist eine Stepper-Komponente in React?

Eine Fortschrittsanzeige für eine Aufgabe, die in geordnete Schritte aufgeteilt ist, etwa ein Checkout oder eine Registrierung. Sie zeigt, welche Schritte erledigt sind, welcher gerade dran ist und was noch fehlt, und sie kann den Sprung zurück zu einem erledigten Schritt erlauben.

Hat shadcn/ui eine Stepper-Komponente?

Nein. Stand Oktober 2026 hat die offizielle Komponentenliste von shadcn/ui keinen Stepper. Community-Registries wie ReUI veröffentlichen einen, der sich mit der shadcn CLI installieren lässt, und du kannst auch selbst einen aus einer geordneten Liste und Tailwind-Klassen bauen.

Wie mache ich einen React Stepper vertikal?

Ordne die Schritte in einer Spalte an, die Marker auf einer Seite, Titel und Beschreibungen daneben, und verbinde die Marker mit einer senkrechten Linie. In Wingo UI Steps ist das orientation="vertical", und das funktioniert bei jeder Bildschirmbreite.

Wie sollte ein Stepper auf dem Handy aussehen?

Eine Reihe nummerierter Kreise mit Titeln passt selten auf einen 360px breiten Bildschirm. Zeig stattdessen einen kompakten Header mit Schrittzahl, aktuellem Titel, nächstem Schritt und Fortschrittsbalken, oder wechsle zu einer vertikalen Liste, wenn die Leute jeden Schritt sehen müssen.

Sollten erledigte Schritte in einem Stepper klickbar sein?

Meistens ja: Zu einem erledigten Schritt zurückzugehen, um etwas zu korrigieren, ist der häufigste Grund, auf einen Stepper zu klicken. Der Sprung nach vorn über nie ausgefüllte Schritte sollte gesperrt bleiben, außer die Schritte sind wirklich unabhängig.