Tour Kit : bibliothèque React headless pour créer des product tours sans UI imposée

React × headless UI = onboarding qui ressemble à ton produit, pas à un plugin générique

Tu veux guider tes utilisateurs à travers ton app React. T’as regardé les SaaS d’onboarding, t’as vu les prix, et t’as réalisé que tu vas passer autant de temps à contourner leur UI qu’à la configurer. Tour Kit existe pour ça : tu contrôles tout, la lib ne fait que la logique. Aujourd’hui tu vas apprendre à :

• Installer Tour Kit et comprendre son architecture en packages séparés
• Configurer un product tour headless compatible avec ton design system existant
• Orchestrer les étapes, les triggers et la navigation sans composants imposés
• Comparer Tour Kit aux alternatives open-source et SaaS pour décider si c’est le bon choix
• Identifier les vrais manques de la lib avant de l’engager dans ton codebase

Ce dont t’as besoin avant de commencer

1. Un projet React fonctionnel

Tour Kit cible les apps React modernes. Next.js, Remix, Vite : peu importe, tant que tu gères du JSX et que t’as accès à ton arbre de composants. Sans React dans ton stack, c’est la mauvaise adresse.

2. Un gestionnaire de paquets (npm, pnpm, yarn)

La lib se distribue en plusieurs packages séparés sur npm. Tu vas en installer quelques-uns selon les fonctionnalités dont tu as besoin.

3. Un design system existant (optionnel mais recommandé)

Tour Kit brille quand tu as déjà shadcn/ui, Radix UI ou Tailwind en place. Si tu pars de zéro sans système de styles, t’auras plus de travail à faire côté UI, mais c’est faisable.

4. Accès au repository GitHub ou à la doc officielle

La documentation primaire est sur GitHub. Garde l’onglet ouvert pendant l’intégration.

Le workflow, étape par étape

Tour Kit est architecturé en une dizaine de packages distincts. Le core gzippé pèse moins de 8 KB. C’est intentionnel : chaque package couvre une responsabilité précise (gestion des étapes, positionnement des tooltips, persistance d’état, etc.). Tu évites de charger du code mort.

npm install @tour-kit/core @tour-kit/react
# Ajoute les packages selon tes besoins :
# @tour-kit/pointer, @tour-kit/overlay, @tour-kit/progress

La configuration d’un tour dans Tour Kit suit un pattern déclaratif. Tu définis un tableau d’étapes, et la lib s’occupe de l’état, de la navigation et du positionnement.

const tourSteps = [
{
target: "-menu",
title: "Ton menu principal",
content: "Toutes tes fonctions principales sont ici.",
placement: "bottom",
},
{
target: "-widget",
title: "Ton tableau de bord",
content: "Vue d'ensemble en temps réel.",
placement: "right",
},
{
target: "-button",
title: "Paramètres",
content: "Configure ton compte ici.",
placement: "left",
},
];

Chaque objet target utilise un sélecteur CSS standard. Ça veut dire que tu n’as pas à ajouter d’attributs spéciaux dans ton HTML si tes éléments ont déjà des IDs ou des classes stables. La lib cible l’élément, calcule sa position dans le DOM, et passe l’information à ton composant de tooltip.

C’est là que le mot “headless” prend tout son sens. Tour Kit ne te donne pas un <Tooltip> pré-stylé. Il te donne un hook ou un provider qui expose l’état du tour courant, et c’est toi qui décides comment afficher ça.

import { useTourStep } from "@tour-kit/react";
function MonTooltip() {
const { currentStep, totalSteps, next, prev, close } = useTourStep();
if (!currentStep) return null;
return (
<div className="rounded-lg border border-border bg-popover p-4 shadow-md">
<h3 className="text-sm font-semibold">{currentStep.title}</h3>
<p className="mt-1 text-sm text-muted-foreground">{currentStep.content}</p>
<div className="mt-3 flex items-center justify-between">
<span className="text-xs text-muted-foreground">
{currentStep.index + 1} / {totalSteps}
</span>
<div className="flex gap-2">
{currentStep.index > 0 && (
<button onClick={prev} className="text-xs">Précédent</button>
)}
<button onClick={next} className="text-xs font-medium">
{currentStep.index === totalSteps - 1 ? "Terminer" : "Suivant"}
</button>
</div>
</div>
</div>
);
}

Si ton projet utilise déjà shadcn/ui, tu peux directement utiliser <Card>, <Button>, <Badge> de shadcn dans ce composant. Zéro conflit de styles parce que Tour Kit n’injecte rien lui-même dans le DOM côté apparence.

import { TourProvider, useTour } from "@tour-kit/react";
function App() {
return (
<TourProvider steps={tourSteps} tooltip={<MonTooltip />}>
<MonApplication />
</TourProvider>
);
}
// Dans un composant enfant :
function BoutonDebutTour() {
const { start } = useTour();
return (
<button onClick={() => start()}>
Voir la visite guidée
</button>
);
}

Tu peux déclencher le tour au onMount, à la première connexion d’un utilisateur, ou sur clic manuel. La lib ne dicte pas le moment : c’est toi qui appelles start(). Cette flexibilité est non-négligeable quand tu veux conditionner l’onboarding à un flag Supabase ou à une valeur dans ton state global.

Le positionnement est géré par la lib : elle lit les coordonnées de l’élément cible dans le viewport et passe ces données à ton composant. Tu n’as pas à calculer de getBoundingClientRect() à la main. Pour l’effet spotlight (assombrir le reste de l’écran et mettre en évidence l’élément ciblé), tu actives le package @tour-kit/overlay. Ça ajoute un layer CSS configurable autour de l’élément. La couleur, l’opacité, le border-radius du spotlight : tout ça reste dans ton CSS, pas dans des props opaques de la lib.

import { TourOverlay } from "@tour-kit/overlay";
// Dans ton TourProvider :
<TourProvider steps={tourSteps} tooltip={<MonTooltip />} overlay={<TourOverlay />}>
<MonApplication />
</TourProvider>

Le hic

Soyons clairs sur ce que Tour Kit ne fait pas. Pas d’analytics intégrés. Tu ne sais pas combien d’utilisateurs terminent le tour, où ils abandonnent, ni quelle étape génère de la friction. Si tu veux ces données, tu dois brancher ton propre système d’événements (Posthog, Segment, un simple log côté serveur). C’est du travail supplémentaire que les SaaS incluent par défaut. Pas d’interface no-code. Ton équipe produit ne peut pas modifier les étapes du tour sans passer par du code. Chez Appcues, un PM peut créer un nouveau tour depuis une interface web sans toucher une ligne de TypeScript. Avec Tour Kit, chaque changement de contenu passe par un PR. Si ton équipe n’a pas de ressources frontend disponibles, c’est un blocage réel. Pas de targeting comportemental out-of-the-box. Les SaaS d’onboarding permettent de cibler des segments d’utilisateurs (rôle, plan, date d’inscription) directement depuis leur dashboard. Tour Kit, tu gères ça dans ton code en conditionnant start() à tes propres règles métier. C’est plus de contrôle, mais plus de code à écrire et à maintenir. La courbe d’apprentissage est réelle. Pour une équipe sans frontend dédié, l’approche headless peut ralentir l’itération. Le premier tour prend du temps à configurer correctement, surtout si tu veux gérer des cas limites (éléments qui s’affichent en lazy load, modals qui ouvrent une cible). Driver.js mérite d’être mentionné. À titre de comparaison, Driver.js offre un bundle de taille similaire à Tour Kit avec plus de 25 000 étoiles GitHub. Il n’est pas headless au même degré, mais il inclut une couche UI par défaut et une API très simple. Pour un projet sans design system établi, Driver.js peut démarrer plus vite.

Quelques trucs bons à savoir

• Tour Kit pèse moins de 8 KB gzippé pour le core, ce qui le rend presque invisible sur ton budget bundle.
• React Joyride, alternative populaire, pèse environ 45 KB gzippé, soit environ cinq fois plus, avec plus de 600 000 téléchargements hebdomadaires sur npm. C’est la lib la plus utilisée dans cet espace, mais son empreinte est notable.
• La licence Pro à $99 (one-time) débloque des fonctionnalités avancées selon la doc; vérifie la liste exacte sur le repo avant d’acheter.
• Aucun script tiers n’est injecté, ce qui simplifie la conformité aux politiques CSP strictes et aux exigences SOC 2 de certains clients enterprise.
• Le package @tour-kit/overlay est optionnel : si tu n’utilises pas le spotlight, tu ne l’importes pas.
• Si ton app charge des sections en lazy load (routes dynamiques, composants différés), l’élément cible peut ne pas exister dans le DOM au moment où la lib le cherche. Prévois une logique de retry ou de délai pour ces cas.

Check-list finale

Verdict + prochaines étapes

Tour Kit est le bon choix si tu as du frontend disponible, un design system établi, et que tu refuses de payer un abonnement mensuel à un SaaS pour un use case que tu peux contrôler entièrement dans ta codebase. La contrainte CSP et SOC 2 est un argument de vente réel pour les équipes qui vendent à des clients enterprise sensibles à la sécurité. Évite-le si ton équipe produit a besoin d’itérer sur le contenu des tours sans passer par du code, ou si tu veux des analytics d’onboarding sans construire l’infrastructure toi-même. Prochaine étape : installe le package core, définis deux ou trois étapes sur ta feature principale, et rends le composant tooltip dans ton design system existant. Le premier tour fonctionnel te prendra une après-midi. C’est là que tu évalues si l’approche headless colle à ton rythme d’itération.

Texte par David Cyr

David Cyr

L'Opérateur AI · Fondateur Taverne AI

Opérateur québécois. J'ai construit LeadLoup, un mandat acheteur véhicules pour Complexe Kia, et plusieurs systèmes IA en production. À la Taverne, je teste des outils qu'on me paie pour utiliser, et je dis si c'est utile ou si c'est de la marde.

À propos·Méthodologie