Onboarding Checkliste UI: Die Get-started-Karte in React

Die Onboarding Checkliste UI ist die Get-started-Karte, die ein neuer Kunde nach der Registrierung im Dashboard sieht: vier oder fünf Aufgaben, ein Fortschrittsbalken, neben jeder Aufgabe ein Button. Viele Beispiele für eine React Onboarding Checkliste hören bei einer Liste mit Checkboxen auf. Eine echte muss schwierigere Fragen beantworten: Welche Aufgaben gehören darauf, wo wird der Fortschritt gespeichert, was passiert, wenn jemand sie ausblendet, wie passt sie auf ein Smartphone, und wie übergibt sie an eine Produkttour, ohne zu nerven? Dieser Guide beantwortet jede davon mit der Setup Checklist von Wingo UI und schlichtem Next.js-Code zum Kopieren.

Welche Aufgaben gehören auf eine SaaS Onboarding Checkliste?

Die Aufgaben, die ein neues Konto zu seinem ersten echten Ergebnis bringen. Bei einer Rechnungs-App heißt das: Zahlungen verbinden und die erste Rechnung senden, nicht ein Profil ausfüllen. Eine nützliche SaaS Onboarding Checkliste folgt vier Regeln:

1. Drei bis fünf gezählte Aufgaben. Jede bringt das Konto näher an die Arbeit, für die es angelegt wurde.
2. Jede Aufgabe hat eine Aktion. „Stripe verbinden“ öffnet den Stripe-Flow. Eine Aufgabe, über die man nur lesen kann, ist eine To-do-Notiz, kein Onboarding.
3. Optionale Schritte zählen nicht mit. „Mobile App holen“ ist nett, mehr nicht. Markier sie als optional, damit der Balken auch ohne sie 100% erreicht.
4. Nur echter Vorsprung. Hat die Registrierung den Workspace schon angelegt, zeig diese Aufgabe als erledigt. In ihrer Studie zum Endowed Progress Effect (opens in a new tab) (Journal of Consumer Research, 2006) gaben Nunes und Drèze Kunden einer Autowaschanlage Treuekarten, auf denen schon zwei von zehn Stempeln standen. Diese Kunden füllten ihre Karte häufiger bis zum Ende als Leute mit einer leeren Karte für acht Stempel. Rechne auf einer Checkliste nur Schritte an, die die Person wirklich erledigt hat, dann bleibt der Vorsprung ehrlich. Ein Balken, der fürs Öffnen der App 20% anzeigt, wirkt wie ein Trick.

Wie baue ich die Get-started-Karte in React?

Eine Get-started-Checkliste ist eine Komponente mit einer Liste von Einträgen. Installier sie mit npx wingo-ui@latest add setup-checklist. Die CLI kopiert setup-checklist.tsx nach components/ui, zusammen mit dem Progress Balken, Button und Popover, die sie nutzt, und installiert motion und lucide-react. Dann gibst du ihr die Aufgaben:

"use client";

import { useState } from "react";
import { Building2, CreditCard, FileText, Palette, Smartphone } from "lucide-react";
import { SetupChecklist, type SetupChecklistItem } from "@/components/ui/setup-checklist";

const items: SetupChecklistItem[] = [
  { id: "workspace", title: "Workspace anlegen", icon: <Building2 /> },
  {
    id: "logo",
    title: "Logo hinzufügen",
    description: "Es erscheint auf Rechnungen und im Kundenportal.",
    icon: <Palette />,
    action: { label: "Logo hochladen", href: "/settings/brand" },
  },
  {
    id: "payments",
    title: "Zahlungen verbinden",
    description: "Kunden zahlen per Karte oder Überweisung.",
    icon: <CreditCard />,
    action: { label: "Stripe verbinden", href: "/settings/payments" },
  },
  {
    id: "invoice",
    title: "Erste Rechnung senden",
    icon: <FileText />,
    action: { label: "Rechnung erstellen", href: "/invoices/new" },
  },
  { id: "app", title: "Mobile App holen", icon: <Smartphone />, optional: true, action: { label: "Link per SMS senden" } },
];

export function GetStarted() {
  const [completed, setCompleted] = useState<string[]>(["workspace"]);
  return <SetupChecklist items={items} completed={completed} onCompletedChange={setCompleted} />;
}

Ohne weitere Props außer den Einträgen bekommst du schon eine fertige Karte: den Titel „Get started“, eine Zählung „x of y done“ mit Balken, die erste offene Aufgabe aufgeklappt und immer nur eine Aufgabe offen. Sobald du onCompletedChange anschließt, wird jeder runde Haken zu einer Checkbox, die die Leute umschalten können. Ohne zeigen die Haken nur den Zustand an. Genau das willst du, wenn der Server entscheidet, was erledigt ist. Ein Eintrag mit eigenem done bleibt in beiden Fällen schreibgeschützt. Wird die letzte gezählte Aufgabe abgehakt, ersetzt ein Panel „You're all set“ die Liste, und die Karte klappt nach doneDelay zusammen (standardmäßig 4000 ms; 0 lässt sie offen).

tone steht standardmäßig auf neutral, und im Dashboard lassen wir es dabei, denn eine Karte in Markenorange konkurriert mit der Hauptaktion der Seite. size="sm" zusammen mit variant="inline" bringt die Karte in eine Sidebar.

Wo sollte der Fortschritt der Onboarding-Checkliste liegen?

Auf dem Server. Fortschritt in React-State oder im Local Storage ist auf einem neuen Laptop weg und veraltet, wenn jemand Stripe über die Einstellungen verbindet statt über die Karte. Teil die Aufgaben in zwei Arten:

• Aufgaben, die deine Daten schon kennen. Logo hochgeladen, Stripe verbunden, erste Rechnung gesendet. Berechne sie auf dem Server und gib dem Eintrag done mit. Das done eines Eintrags schlägt completed, der Haken kann sich also nicht von der Wirklichkeit entfernen.
• Aufgaben, die nur die Person bestätigen kann. „Tour angesehen“, „Mobile App übersprungen“. Diese IDs legst du in einem kleinen Datensatz am Nutzer ab und speicherst ihn mit einer Server Action.

// app/(app)/dashboard/page.tsx (Server Component)
import { getOnboarding } from "@/lib/onboarding"; // deine Datenschicht
import { GetStarted } from "./get-started";

export default async function Dashboard() {
  const o = await getOnboarding();
  return (
    <GetStarted
      facts={{ workspace: true, logo: o.hasLogo, payments: o.stripeConnected, invoice: o.invoiceCount > 0 }}
      manual={o.manualDone}
      dismissed={o.dismissedAt !== null}
    />
  );
}

// app/(app)/dashboard/get-started.tsx
"use client";

import { useState } from "react";
import { SetupChecklist } from "@/components/ui/setup-checklist";
import { saveOnboarding } from "./actions"; // "use server"-Funktion, die manualDone / dismissedAt schreibt
import { items } from "./checklist-items";

type Props = { facts: Record<string, boolean>; manual: string[]; dismissed: boolean };

export function GetStarted({ facts, manual, dismissed }: Props) {
  const [completed, setCompleted] = useState(manual);
  if (dismissed) return null;
  return (
    <SetupChecklist
      items={items.map((item) => (item.id in facts ? { ...item, done: facts[item.id] } : item))}
      completed={completed}
      onCompletedChange={(next) => {
        setCompleted(next);
        void saveOnboarding({ manualDone: next });
      }}
      onDismiss={() => void saveOnboarding({ dismissed: true })}
    />
  );
}

Aufgaben mit Datenbasis springen beim nächsten Rendern auf erledigt, egal wo sie abgeschlossen wurden. Erledigt deine Aktion die Aufgabe wirklich an Ort und Stelle (ein Verbinden-Button, der den ganzen OAuth-Flow in einem Pop-up durchläuft), hakt markOnAction den Eintrag ab, sobald seine Hauptaktion geklickt wird.

Wie sollten Ausblenden und Zurückholen funktionieren?

Ausblenden versteckt die Karte für diese Person, bis sie sie wieder anfordert. Das x im Header (und der Button Dismiss im Fertig-Zustand) blendet die Komponente aus und ruft onDismiss auf. Speichere das, sonst ist die Karte beim nächsten Laden der Seite wieder da, und die Leute gewöhnen sich an, sie zu übersehen.

Das Zurückholen ist dein Teil. Leg im Hilfe- oder Konto-Menü einen Eintrag „Setup-Guide“ an, der eine Server Action aufruft: Sie löscht dismissedAt und ruft revalidatePath("/dashboard") auf. Das Dashboard rendert neu mit dismissed auf false, die Checkliste wird frisch gemountet und zeigt den aktuellen Fortschritt, und jede Aufgabe mit Datenbasis ist auf dem neuesten Stand. Zwei Details sind wichtig:

• Halte das Überspringen einer Aufgabe und das Ausblenden der ganzen Liste auseinander. Gib der Aufgabe Team einladen eine secondaryAction wie „Vorerst überspringen“, deren onClick diese ID zu completed hinzufügt und speichert. Der Rest der Liste bleibt dann stehen.
• Nimm die Karte weg, wenn das Konto eindeutig aktiv ist. Wer zehn Rechnungen ohne Logo verschickt hat, braucht sie nicht mehr; setz auf dem Server dasselbe Flag dismissedAt.

Wann sollte die Checkliste zum schwebenden Launcher werden?

Wenn die Seite keinen Platz für eine Karte hat oder die Checkliste die Leute durch die App begleiten soll. variant="floating" rendert in der unteren Ecke eine Pille mit Titel und Zählung. Sie öffnet die Liste am Desktop in einem Popover und unter 768px in einem Bottom Sheet, und dank Safe-Area-Insets hält sie Abstand zum Home-Indikator des iPhones. Die Demo unten startet in der Floating-Variante: Tipp auf die Pille.

Ein Muster, das gut funktioniert: die Karte auf der Startseite des Dashboards, der Launcher auf den anderen Seiten, bis das Konto alles erledigt oder ihn ausblendet, und beide lesen denselben Datensatz auf dem Server. Das schwebende Panel startet immer geschlossen, es verdeckt beim Laden also nie die Seite.

Wie übergibt die Checkliste an eine Produkttour, ohne zu nerven?

Mach die Tour zu einer Aufgabe statt zu einem Pop-up. Eine Tour, die automatisch über einer Checkliste startet, die ebenfalls Aufmerksamkeit will, ist der schlechteste erste Besuch. Setz „Die 1-Minuten-Tour ansehen“ als optionale Aufgabe auf die Liste, starte die Tour aus ihrer Aktion und hak die Aufgabe ab, sobald die Tour endet, egal wie:

"use client";

import { useRef, useState } from "react";
import { Compass } from "lucide-react";
import { SetupChecklist, type SetupChecklistItem } from "@/components/ui/setup-checklist";
import { Tour, type TourApi, type TourStep } from "@/components/ui/tour";

const steps: TourStep[] = [
  { id: "new", target: "#new-invoice", title: "Rechnung erstellen", content: "Jede Rechnung beginnt hier." },
  { id: "clients", target: "#clients-nav", title: "Deine Kunden", content: "Kontakte, Verlauf und Salden." },
];

export function GetStartedWithTour({ items }: { items: SetupChecklistItem[] }) {
  const tour = useRef<TourApi | null>(null);
  const [completed, setCompleted] = useState<string[]>([]);
  const finish = () => setCompleted((ids) => (ids.includes("tour") ? ids : [...ids, "tour"]));

  const withTour: SetupChecklistItem[] = [
    ...items,
    {
      id: "tour",
      title: "Die 1-Minuten-Tour ansehen",
      icon: <Compass />,
      optional: true,
      action: { label: "Tour starten", onClick: () => tour.current?.start() },
    },
  ];

  return (
    <>
      <SetupChecklist items={withTour} completed={completed} onCompletedChange={setCompleted} />
      <Tour steps={steps} persistKey="acme:tour" setApi={(api) => { tour.current = api; }} onComplete={finish} onSkip={finish} />
    </>
  );
}

Hier fehlt autoStart mit Absicht. Die Person entscheidet, wann sie die Tour sieht, persistKey merkt sich im Local Storage, dass sie beendet oder übersprungen wurde, und start() spielt sie später trotzdem über das Hilfe-Menü erneut ab. Local Storage gilt pro Browser, deshalb sollte finish im Produktiveinsatz die ID tour zusätzlich mit den anderen manuellen IDs speichern, wie im Server-Beispiel oben; dieser Datensatz ist der, der die Leute auf ein neues Gerät begleitet. Bei der Floating-Variante steuerst du ihr Prop open und schließt das Panel, bevor du start() aufrufst, damit das Spotlight nicht hinter der Liste verschwindet. Das komplette Setup der Tour, samt angedockter Smartphone-Karte, steht in unserem Guide zur React Product Tour.

Die Checkliste kommt nach dem First-Run-Flow, nicht mittendrin. Begrüßungsfolien, Berechtigungsabfragen und der Profilschritt gehören in den Onboarding Flow, der im Dashboard endet, wo die Checkliste übernimmt (siehe unser Tutorial zum React Onboarding Flow).

Funktioniert sie am Smartphone und mit der Tastatur?

Ja. Jeder Aufgaben-Header ist ein echter Button mit aria-expanded, und der Haken ist eine role="checkbox" mit aria-checked, sobald du onCompletedChange anschließt. Tab erreicht jede Aufgabe, Pfeil hoch, Pfeil runter, Pos1 und Ende wechseln zwischen ihnen, Enter oder Leertaste klappt eine auf, und die Leertaste schaltet einen fokussierten Haken um. Der Fortschrittsbalken bekommt seinen Namen aus dem Zähltext, ein Screenreader liest also „2 of 4 done“ vor. Auf Touchscreens wachsen die Zeilen auf 44px, und unter 640px nehmen die Aktions-Buttons die volle Breite ein, damit der Daumen die Aufgabe trifft, die er meint.

Wie schneidet sie gegen shadcn Onboarding-Checklisten-Blöcke ab?

shadcn/ui hat keine eigene Checklisten-Komponente. Wer eine shadcn onboarding checklist sucht, landet deshalb bei einer Registry von Drittanbietern. Das sagen die öffentlichen Seiten, Stand 6. November 2026:

Für einen Prototyp reicht ein Community-Block. Für den Produktiveinsatz prüfst du vor der Wahl den gespeicherten Fortschritt, das Smartphone-Layout und die Tastaturbedienung.

Wie baue ich sie in meine App ein?

Führ npx wingo-ui@latest add setup-checklist aus, bilde deine Einrichtungsaufgaben auf Einträge ab, deren done aus deinen eigenen Daten kommt, und speichere die manuellen IDs und das Ausblenden am Nutzer. Setup Checklist und Tour gehören zu Wingo UI Pro ($8 im Monat, $80 im Jahr oder einmalig $150); der Balken Progress ist kostenlos, falls du lieber selbst eine einfachere Karte baust. Brauchst du auch das Dashboard drumherum, liefert dir der Pro-Block Admin Dashboard Page die Shell und einen Startscreen für die Karte. Weitere komplette Screens findest du unter Praxis: Screens und Apps, angefangen mit dem Tutorial zum Next.js Admin Dashboard.

Häufige Fragen

Wie viele Aufgaben sollte eine Onboarding-Checkliste haben?

Drei bis fünf, und jede führt zu einem echten Ergebnis, etwa Zahlungen verbinden oder die erste Rechnung senden. Markier Schritte, die nur nett sind, als optional, damit sie nicht mitzählen, und verleg fortgeschrittene Einstellungen an die Stellen, an denen die Leute sie brauchen.

Sollte eine Onboarding-Checkliste schon teilweise erledigt starten?

Nur mit Schritten, die die Leute wirklich gemacht haben, etwa den Workspace bei der Registrierung anzulegen. Ein Vorsprung aus erledigter Arbeit zeigt, dass sie schon unterwegs sind; ein Balken, der nichts anrechnet, wirkt wie ein Trick.

Wo speichere ich den Fortschritt einer Onboarding-Checkliste?

Auf dem Server, beim Nutzer oder Workspace. Leite Aufgaben wie Stripe verbinden aus deinen eigenen Daten ab und speichere die manuellen sowie das Ausblenden in einem kleinen Datensatz, damit der Fortschritt auf ein neues Smartphone oder in einen anderen Browser mitkommt.

Kann man die Onboarding-Checkliste ausblenden und zurückholen?

Das sollte gehen. Blende sie beim Schließen aus, speichere das, und leg im Hilfe- oder Konto-Menü einen Eintrag Setup-Guide an, der das Flag löscht und die Karte wieder zeigt.

Gibt es eine shadcn Onboarding Checklist Komponente?

shadcn/ui selbst hat Stand November 2026 keine Checklisten-Komponente. Registries von Drittanbietern wie shadcn.io und 21st.dev führen Onboarding-Checklisten-Blöcke, und die Setup Checklist von Wingo UI installierst du genauso mit npx wingo-ui@latest add setup-checklist.

Ist die Setup Checklist von Wingo UI kostenlos?

Nein. Setup Checklist, Tour und Onboarding Flow sind Pro. Die Komponente Progress, mit der du selbst eine einfachere Karte bauen kannst, ist kostenlos.