React Product Tour: Spotlight, Smartphone-Dock, Hotspots

Eine React Product Tour sieht in der Demo einfach aus: ein Rahmen um einen Button, eine Karte mit „Weiter“, fünf Schritte, fertig. Dann trifft sie auf eine echte App. Das Ziel steckt in einem geschlossenen Menü, die Karte verdeckt auf einem 390px breiten Bildschirm genau das, was sie beschreibt, Tab wandert in die Seite hinter dem Overlay ab, und wer neu lädt, bekommt die Tour noch einmal. Dieser Guide zeigt, was eine Produkttour im Produktiveinsatz braucht, wie die Tour von Wingo UI Spotlight, Smartphone-Layout und gespeicherten Fortschritt löst, und wann du besser gar keine Tour baust.

Was muss eine React Product Tour können?

Sieben Dinge. Eine geführte React-Tour, die Elemente nur auf einem breiten Bildschirm hervorhebt, deckt das erste ab:

1. Ein Spotlight auf die echte UI. Die Seite abdunkeln, ein abgerundetes Loch um das Ziel schneiden und ihm folgen, wenn die Seite scrollt oder sich die Größe ändert.
2. Ziele, die noch nicht da sind. Ein Schritt kann auf einen Eintrag in einem Menü oder Tab zeigen, der erst noch geöffnet werden muss.
3. Interaktive Schritte. Bei „Drück auf Neue Rechnung“ soll es weitergehen, sobald jemand den echten Button Neue Rechnung drückt.
4. Tastatur und Screenreader. Fokus in der Karte, Pfeiltasten zum Blättern, Escape zum Verlassen, danach Fokus zurück an die alte Stelle.
5. Ein Smartphone-Layout. Eine Karte, die neben einem 44px großen Button schwebt, verdeckt einen halben Smartphone-Bildschirm.
6. Ein Gedächtnis. Beendete oder übersprungene Touren kommen beim nächsten Besuch nicht wieder.
7. Ein Weg zurück. Ein Eintrag im Hilfe-Menü oder ein Shortcut, der sie erneut abspielt.

Wie schneiden die React Tour Libraries im Vergleich ab?

React Joyride ist die etablierte kostenlose React Tour Library, Driver.js eine kleine Library ohne React-Bindings, und Shepherd.js ist nur für nichtkommerzielle Arbeit kostenlos. Diese Namen fallen, wenn du nach einer React Joyride Alternative suchst. Die Fakten stammen aus dem README oder der Website des jeweiligen Projekts, Stand Oktober 2026.

React Joyride ist die sichere Wahl, wenn du ein kostenloses, gepflegtes Paket willst und dich selbst um Smartphones kümmerst. Driver.js passt zu einem Projekt, das nicht komplett auf React läuft. Der Rest dieses Guides behandelt die Tour von Wingo UI, die als Quellcode in components/ui landet.

Welche Props braucht eine React Product Tour?

Nur eins: steps. Jeder Schritt hat eine id, einen title, optional content und media sowie ein target. Das kann ein CSS-Selektor sein, eine Funktion, die ein Element zurückgibt, oder ein Ref. Ein Schritt ohne Ziel, oder einer, dessen Ziel nicht innerhalb einer Sekunde auftaucht, bekommt eine zentrierte Karte. So schreibst du einen Begrüßungs- und einen Abschlussschritt.

npx wingo-ui@latest add tour

"use client";

import { useRef } from "react";
import { Button } from "@/components/ui/button";
import { Tour, type TourStep } from "@/components/ui/tour";

export function ClientsPage() {
  const search = useRef<HTMLInputElement>(null);
  const invoice = useRef<HTMLButtonElement>(null);

  const steps: TourStep[] = [
    { id: "welcome", title: "Willkommen bei Northwind CRM", content: "Hier siehst du, wo alles liegt. Das dauert 30 Sekunden." },
    { id: "search", target: search, title: "Jeden Kunden finden", content: "Gib einen Namen, eine EIN oder eine Stadt ein." },
    { id: "filters", target: "[data-tour='filters']", title: "Gespeicherte Filter", content: "Speichere die Kombinationen, die du oft nutzt." },
    { id: "invoice", target: invoice, title: "Rechnung erstellen", content: "Drück auf Neue Rechnung, um weiterzumachen.", advanceOn: "click" },
    { id: "done", title: "Du bist startklar", content: "Du kannst diese Tour jederzeit über das Hilfe-Menü wiederholen." },
  ];

  return (
    <Tour steps={steps} persistKey="northwind-crm:welcome-tour" autoStart shortcut="shift+h">
      <input ref={search} placeholder="Kunden suchen" />
      <div data-tour="filters">{/* Chips der gespeicherten Filter */}</div>
      <Button ref={invoice}>Neue Rechnung</Button>
    </Tour>
  );
}

Die Tour rendert ihre Children an Ort und Stelle und legt das Overlay in ein Portal. Jeder Schritt scrollt zuerst sein Ziel ins Bild, dann gleitet das Spotlight mit einer Spring-Animation dorthin, und die Karte blendet sich auf der ersten Seite ein, die genug Platz bietet (side="auto" probiert unten, dann oben, dann die breitere von links und rechts). Als Nächstes greifst du zu showProgress (dots, fraction, bar oder none), size (sm für 288px breite Karten, md für 340px), tone, spotlightPadding und spotlightRadius (beide auch pro Schritt einstellbar) und labels für jeden Text.

Starte die Tour unten und folge ihr bis Schritt vier: Dort wartet sie, bis du den echten Button „New invoice“ drückst. Pfeil rechts und Enter gehen weiter, Pfeil links zurück, Escape beendet die Tour.

Wie warten Schritte auf Menüs und echte Klicks?

Drei Optionen pro Schritt reichen dafür. interactive: true lässt Klicks und Eingaben zum hervorgehobenen Element durch, sodass die Leute ins Suchfeld tippen können, während die Karte es erklärt. advanceOn: "click" schließt interactive ein und ruft next auf, sobald jemand das Ziel anklickt. beforeEnter läuft, bevor der Schritt erscheint, und wird bis zu drei Sekunden lang abgewartet. Das genügt, um ein Menü zu öffnen oder einen Tab zu wechseln, damit das Ziel existiert:

{
  id: "export",
  target: exportItemRef,
  title: "Nach Excel exportieren",
  content: "Die gefilterte Liste landet in einer .xlsx-Datei.",
  side: "right",
  beforeEnter: async () => {
    setMenuOpen(true);
    await new Promise((resolve) => requestAnimationFrame(resolve));
  },
},

Schließ das Menü im beforeEnter des nächsten Schritts und in onOpenChange wieder, wenn die Tour endet. Sonst bleibt es nach einem Überspringen offen. Verschwindet ein Ziel, während sein Schritt angezeigt wird, rutscht die Karte in die Mitte, statt ins Leere zu zeigen.

Wie sollte eine Produkttour am Smartphone funktionieren?

Dock die Karte unten an. Unter 768px macht die Tour das standardmäßig (mobileLayout="docked"): Die Karte wird zu einem Sheet über der Safe Area, ihre Buttons Back und Next sind 48px hoch, sie bleibt über der Bildschirmtastatur, sobald diese eingeblendet wird, und ein Ziel außerhalb der oberen 55% des Bildschirms scrollt dort hinein, damit die Karte es nicht verdeckt. Wischst du auf der Karte nach links, kommt der nächste Schritt, nach rechts der vorherige.

Der Grund ist der Daumen. Ein Popover, das an einem Button unten auf dem Smartphone-Bildschirm hängt, liegt genau über der Hand, die auf Next tippen muss. Hängt es nahe am oberen Rand, rutscht Next außer Reichweite. Dieselbe Regel steckt hinter unserem Guide zum React Bottom Sheet. Gib mobileLayout="popover" an, wenn du die Desktop-Karte wirklich auch am Smartphone willst, oder docked, um sie bei jeder Breite anzudocken. Das brauchst du in einem Smartphone-Mockup zusammen mit container.

Wie merke ich mir, wer die Tour beendet hat?

Gib ihr einen persistKey. Die Tour speichert dann completed oder skipped im Local Storage, autoStart (öffnet die Tour 600ms nach der Hydration) lässt eine beendete Tour in Ruhe, start() spielt sie trotzdem erneut ab, und reset() vergisst das Ergebnis. Für ein Gerät reicht das. Bei einer React Onboarding Tour für angemeldete Nutzer speicherst du das Ergebnis zusätzlich auf dem Server, damit ein neuer Laptop sie nicht noch einmal abspielt:

"use client";

import { Button } from "@/components/ui/button";
import { Tour, useTour, type TourStep } from "@/components/ui/tour";

function saveTour(status: "completed" | "skipped") {
  void fetch("/api/me/tours/welcome", {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ status }),
  });
}

function ReplayTour() {
  const tour = useTour();
  if (!tour) return null;
  return (
    <Button variant="ghost" size="sm" onClick={() => tour.start()}>
      Tour wiederholen
    </Button>
  );
}

export function AppShell({ steps, seenTour }: { steps: TourStep[]; seenTour: boolean }) {
  return (
    <Tour
      steps={steps}
      autoStart={!seenTour}
      onComplete={() => saveTour("completed")}
      onSkip={() => saveTour("skipped")}
    >
      <ReplayTour />
      {/* der Rest der App */}
    </Tour>
  );
}

Über useTour() bekommt alles innerhalb der Tour ihre API plus open, step, count und status. Der Button zum Wiederholen kann also in einem Header oder einem Hilfe-Menü sitzen. Für Code außerhalb der Children der Tour liefert dir das Prop setApi dieselben Funktionen start, next, previous, goTo, skip, finish und reset. Es ist immer nur eine Tour zu sehen: Öffnet sich eine zweite, wartet sie, bis die erste geschlossen ist.

Wie mache ich eine Produkttour barrierefrei?

Behandle jede Karte als Dialog. Die Karte der Tour hat role="dialog", aria-modal sowie ein Label und eine Beschreibung, die an Titel und Inhalt des Schritts hängen. Tab bleibt in der Karte, ohne die Seite zu sperren, der Fokus kehrt am Ende der Tour an seine alte Stelle zurück, und eine Live-Region im Modus polite sagt bei jedem Schritt etwa „Step 2 of 5: Find any client“ an, am Ende „Tour closed“ oder „Tour completed“. Das hervorgehobene Element bekommt aria-describedby mit Verweis auf den Text des Schritts, solange der Schritt läuft. Ein Screenreader, der den echten Button vorliest, sagt also auch, was die Tour dazu erklärt.

Klicks auf den abgedunkelten Bereich bewirken standardmäßig nichts (closeOnOverlayClick={false}), damit ein versehentliches Tippen am Smartphone die Tour nicht beendet. Standardmäßig hat jede Karte Skip oder einen Schließen-Button, und Escape überspringt von überall aus. Ist reduzierte Bewegung eingestellt, springt das Spotlight, statt zu gleiten, und die Karten blenden nur ein; der Guide zu prefers-reduced-motion erklärt den Hook dahinter.

Wann ist ein Hotspot besser als eine Tour?

Wenn du auf eine einzige Sache zeigen willst. Der Artikel Onboarding Tutorials vs. Contextual Help (opens in a new tab) der Nielsen Norman Group (Page Laubheimer, Februar 2023) sagt es deutlich: Tutorials unterbrechen die Leute, verbessern nicht unbedingt, wie gut sie ihre Aufgaben erledigen, und sind schnell vergessen. Der Artikel empfiehlt Hilfe, die erscheint, wenn man sie braucht, und die sich leicht schließen und wiederfinden lässt.

TourHotspot ist genau dieses Muster. Es setzt einen pulsierenden Punkt an eine Ecke seines Child-Elements (oder eines beliebigen target) und öffnet einen Tipp, wenn jemand darauf tippt oder klickt, unter 768px als Karte am unteren Rand. Mit persistKey verschwindet der Punkt endgültig, sobald der Tipp einmal gesehen wurde.

import { Button } from "@/components/ui/button";
import { TourHotspot } from "@/components/ui/tour";

<TourHotspot
  title="Neu: Umsatz nach Bundesstaat"
  content="Öffne Berichte, um das neue Diagramm zu sehen."
  persistKey="northwind-crm:hint-reports"
  tone="brand"
>
  <Button variant="soft" size="sm">Berichte</Button>
</TourHotspot>

Eine grobe Aufteilung, die bei uns funktioniert: ein Hotspot für ein neues Feature, eine Coachmark-Tour (spotlight={false}, Karten mit Pfeil und ohne Abdunkeln, die Seite bleibt bedienbar) für zwei oder drei zusammenhängende Änderungen in einem Release, und die volle Spotlight-Tour nur zur Orientierung beim ersten Start einer App mit mehreren Bereichen. Ein einzelner Hinweis an einem Bedienelement, das die Leute schon verstehen, gehört in einen Tooltip oder ein Popover, beide kostenlos.

Brauche ich eine Tour oder einen Onboarding Flow?

Die beiden haben verschiedene Aufgaben. Ein Onboarding Flow läuft, bevor die Leute in der App ankommen: Willkommens-Slides, Berechtigungsabfragen, ein kurzes Profil. Das deckt der Block Onboarding Flow ab, und das Tutorial zum React Onboarding Flow geht ihn durch, inklusive der Frage, warum die Abfrage für Benachrichtigungen eine eigene Karte braucht. Eine Produkttour läuft danach in der App, auf den echten Screens. Wenn du beides hast, beschränk die Tour auf die drei oder vier Stellen, die die Leute in ihrer ersten Woche nutzen.

Was sind die typischen Fehler bei einer Produkttour?

• autoStart ohne persistKey. Die Tour öffnet sich bei jedem Laden der Seite. Kombinier beides, oder steuere autoStart über ein Flag vom Server.
• Zu viele Schritte. Jeder zusätzliche Schritt ist eine weitere Gelegenheit, auf Skip zu drücken, bevor der wichtige Teil kommt. Teil lange Touren nach Bereichen auf und starte jede auf ihrer Seite.
• Schritte, die offensichtliche Bedienelemente erklären. Ein Suchfeld braucht keinen Schritt, außer es durchsucht etwas Unerwartetes.
• Ein Shortcut, der kollidiert. ? öffnet oft einen Dialog mit Tastenkürzeln. Die Tour belegt nichts, bis du shortcut angibst, und unsere Demo nutzt shift+h.
• Ein Selektor, der eine versteckte Kopie trifft. Ein String-Ziel läuft über document.querySelector, das den ersten Treffer liefert. Ist das die Desktop-Toolbar, die am Smartphone versteckt ist, zeigt der Schritt eine zentrierte Karte. Nimm einen Ref oder eine Funktion, die das sichtbare Element zurückgibt, und beforeEnter für alles, was länger als eine Sekunde zum Rendern braucht.

Wie baue ich die Tour in mein Projekt ein?

Führ npx wingo-ui@latest add tour aus. Die CLI kopiert tour.tsx nach components/ui, ergänzt die Komponenten Button, Kbd und Progress sowie die Hooks und Helfer, die sie nutzt, und installiert @radix-ui/react-popover, motion und lucide-react. Die Tour und der Onboarding Flow sind Pro-Komponenten (Preise). Weitere Deep Dives zu einzelnen Komponenten findest du in der Kategorie Komponenten-Guides, und der Guide zu React-Formularkomponenten wendet dieselben Regeln für Tastatur, Touch und Screenreader auf jedes Formularelement an.

Häufige Fragen

Welche React Tour Library ist die beste?

React Joyride ist die etablierteste kostenlose Option: MIT-lizenziert, mit einer Joyride-Komponente und einem useJoyride Hook, laut README für React 16.8 bis 19. Driver.js ist eine kleine MIT-Library ohne Framework-Bindung, und Shepherd.js braucht für kommerzielle Nutzung eine kommerzielle Lizenz. Nimm eine Quellcode-Komponente wie die Tour von Wingo UI, wenn du den Code ändern willst und ein fertiges Smartphone-Layout brauchst.

Wie zeige ich eine Produkttour in React nur einmal?

Speichere das Ergebnis. Bei der Tour von Wingo UI legt persistKey completed oder skipped im Local Storage ab, und autoStart lässt eine beendete Tour in Ruhe. Für angemeldete Nutzer speicherst du es zusätzlich in onComplete und onSkip im Nutzerdatensatz, damit ein neues Gerät sie nicht noch einmal abspielt.

Sollte man eine Produkttour überspringen können?

Ja, bei jedem Schritt. Die Nielsen Norman Group hat festgestellt, dass Tutorials, die gleich zu Beginn kommen, die Leute unterbrechen und schnell vergessen werden. Mach das Verlassen also wenigstens leicht und lass die Tour später über ein Hilfe-Menü wieder starten.

Was ist der Unterschied zwischen einer Produkttour und einem Hotspot?

Eine Tour drängt den Leuten eine Folge von Schritten auf, meist beim ersten Start. Ein Hotspot ist ein kleiner pulsierender Punkt an einem Element, der einen Tipp nur öffnet, wenn jemand darauf tippt. Er passt also, um ein neues Feature anzukündigen, ohne die Arbeit zu unterbrechen.

Ist die Tour von Wingo UI kostenlos?

Nein. Die Tour und der Onboarding Flow Block sind Pro. Die Komponenten Popover und Tooltip, die einzelne Hinweise ohne Abfolge abdecken, sind kostenlos.