# Onboarding Checkliste UI: Die Get-started-Karte in React
> So baust du eine Onboarding Checkliste UI in React: welche Aufgaben, Fortschritt auf dem Server, Ausblenden und Zurückholen, Launcher und ruhige Tour-Übergabe.
- Autor: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Veröffentlicht: 6. Nov. 2026
- Kategorie: [Praxis: Screens und Apps](https://wingo-ui.com/de/blog/category/build)
- Lesezeit: 9 Min.
- Kanonische URL: https://wingo-ui.com/de/blog/onboarding-checklist-ui
- Englische Fassung: https://wingo-ui.com/blog/onboarding-checklist-ui
## Kurz gesagt
Eine gute Onboarding Checkliste UI ist eine Get-started-Karte im Dashboard mit drei bis fünf Aufgaben. Jede hat einen Button, der die Aufgabe direkt erledigt, und der Fortschritt zählt nur echte Arbeit. Speichere Fortschritt und Ausblenden am Nutzerdatensatz, damit beides ein neues Gerät übersteht, lass die Leute die Karte ausblenden und über ein Hilfe-Menü zurückholen, und nimm auf Seiten ohne Platz für eine Karte einen schwebenden Launcher. Starte die Produkttour aus einer Aufgabe der Checkliste, statt beides automatisch zu öffnen.
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](https://wingo-ui.com/components/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](https://doi.org/10.1086/500480) (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](https://wingo-ui.com/components/progress) Balken, Button und Popover, die sie nutzt, und installiert `motion` und `lucide-react`. Dann gibst du ihr die Aufgaben:
```tsx
"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: },
{
id: "logo",
title: "Logo hinzufügen",
description: "Es erscheint auf Rechnungen und im Kundenportal.",
icon: ,
action: { label: "Logo hochladen", href: "/settings/brand" },
},
{
id: "payments",
title: "Zahlungen verbinden",
description: "Kunden zahlen per Karte oder Überweisung.",
icon: ,
action: { label: "Stripe verbinden", href: "/settings/payments" },
},
{
id: "invoice",
title: "Erste Rechnung senden",
icon: ,
action: { label: "Rechnung erstellen", href: "/invoices/new" },
},
{ id: "app", title: "Mobile App holen", icon: , optional: true, action: { label: "Link per SMS senden" } },
];
export function GetStarted() {
const [completed, setCompleted] = useState(["workspace"]);
return ;
}
```
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).
> Live-Demo (Setup Checklist): Hak einen Schritt ab: Der Haken ploppt auf, der Balken füllt sich, und der nächste offene Schritt klappt auf. Über den Header klappst du die Karte zusammen. Probier sie unter [Setup Checklist](https://wingo-ui.com/components/setup-checklist) aus und installier sie mit `npx wingo-ui@latest add setup-checklist`.
`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.
```tsx
// 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 (
0 }}
manual={o.manualDone}
dismissed={o.dismissedAt !== null}
/>
);
}
```
```tsx
// 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; manual: string[]; dismissed: boolean };
export function GetStarted({ facts, manual, dismissed }: Props) {
const [completed, setCompleted] = useState(manual);
if (dismissed) return null;
return (
(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.
> Live-Demo (Setup Checklist): Tipp auf den Launcher in der Ecke: Am Desktop öffnet sich die Liste in einem Popover, bei Smartphone-Breite in einem Bottom Sheet. Probier sie unter [Setup Checklist](https://wingo-ui.com/components/setup-checklist) aus und installier sie mit `npx wingo-ui@latest add setup-checklist`.
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](https://wingo-ui.com/components/tour) aus ihrer Aktion und hak die Aufgabe ab, sobald die Tour endet, egal wie:
```tsx
"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(null);
const [completed, setCompleted] = useState([]);
const finish = () => setCompleted((ids) => (ids.includes("tour") ? ids : [...ids, "tour"]));
const withTour: SetupChecklistItem[] = [
...items,
{
id: "tour",
title: "Die 1-Minuten-Tour ansehen",
icon: ,
optional: true,
action: { label: "Tour starten", onClick: () => tour.current?.start() },
},
];
return (
<>
{ 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](https://wingo-ui.com/de/blog/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](https://wingo-ui.com/components/onboarding-flow), der im Dashboard endet, wo die Checkliste übernimmt (siehe unser [Tutorial zum React Onboarding Flow](https://wingo-ui.com/de/blog/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:
| Option | Was die Seite zeigt | Gespeicherter Fortschritt | Zugang |
|---|---|---|---|
| [shadcn.io Setup Checklist Block](https://www.shadcn.io/blocks/onboarding-checklist) | Immer ein Schritt offen, eine Zählung mit Fortschrittslinie, „Hide guide“ klappt ihn zu einer Pille zusammen, die ihn zurückholt | Laut Seite wird nichts gespeichert, die Flags legst du selbst am Konto ab | Teil von shadcn.io Pro; laut Website nicht mit shadcn/ui verbunden |
| [21st.dev Onboarding Checklist](https://21st.dev/@kavikatiyar/components/onboarding-checklist.md) | Aufklappbare Schritte mit den Zuständen erledigt, in Arbeit und offen | Nicht dokumentiert | Installation mit einem 21st-API-Key; Lizenz als unbekannt angegeben |
| [Wingo UI Setup Checklist](https://wingo-ui.com/components/setup-checklist) | Varianten Card, Inline und Floating, Fertig-Zustand, optionale Aufgaben, Bottom Sheet am Smartphone | Kontrolliertes `completed` und `done` pro Eintrag aus deinen Daten | Wingo UI Pro |
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](https://wingo-ui.com/de/pricing) ($8 im Monat, $80 im Jahr oder einmalig $150); der Balken [Progress](https://wingo-ui.com/components/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](https://wingo-ui.com/components/admin-dashboard-page) die Shell und einen Startscreen für die Karte. Weitere komplette Screens findest du unter [Praxis: Screens und Apps](https://wingo-ui.com/de/blog/category/build), angefangen mit dem [Tutorial zum Next.js Admin Dashboard](https://wingo-ui.com/de/blog/nextjs-admin-dashboard-tutorial).
## Komponenten in diesem Artikel
- [Setup Checklist](https://wingo-ui.com/components/setup-checklist) (Pro): The dashboard Get started card: setup tasks with progress and actions, collapsible and dismissible, or a floating launcher. Installation: `npx wingo-ui@latest add setup-checklist`
- [Onboarding Flow](https://wingo-ui.com/components/onboarding-flow) (Pro): A React onboarding flow for a marketplace app: welcome slides, notification and location asks, a short profile, preferences and a finish. Installation: `npx wingo-ui@latest add onboarding-flow`
- [Progress](https://wingo-ui.com/components/progress) (Free): A React progress bar, stepped bar or ring for uploads and quotas, determinate or indeterminate, with a label, value, tones and thresholds. Installation: `npx wingo-ui@latest add progress`
- [Tour](https://wingo-ui.com/components/tour) (Pro): A React product tour that dims the page around the real UI, explains each step in a card, docks at the bottom on phones and adds hotspots. Installation: `npx wingo-ui@latest add tour`
## 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.
---
Quelle: https://wingo-ui.com/de/blog/onboarding-checklist-ui