Step-by-step guided tour dialog with optional image panels and keyboard navigation
Install
npx shadcn add https://ui.happenings.social/r/guided-tour.json
Or with namespace
npx shadcn add @happenings/guided-tour
Preview
Dependencies
src/components/ui/guided-tour.tsx
"use client"
import * as React from "react"
import { Dialog as DialogPrimitive } from "radix-ui"
import { cn } from "@/lib/utils"
import { Button } from "./button"
interface GuidedTourStep {
title: string
description: string
image?: React.ReactNode
}
interface GuidedTourProps {
open: boolean
onOpenChange: (open: boolean) => void
steps: GuidedTourStep[]
onComplete?: () => void
previousLabel?: string
nextLabel?: string
doneLabel?: string
}
function GuidedTour({
open,
onOpenChange,
steps,
onComplete,
previousLabel = "Previous",
nextLabel = "Next",
doneLabel = "Done",
}: GuidedTourProps) {
const [currentStep, setCurrentStep] = React.useState(0)
const step = steps[currentStep]
const isFirst = currentStep === 0
const isLast = currentStep === steps.length - 1
React.useEffect(() => {
if (open) setCurrentStep(0)
}, [open])
const goNext = React.useCallback(() => {
if (isLast) {
onOpenChange(false)
onComplete?.()
} else {
setCurrentStep((s) => s + 1)
}
}, [isLast, onOpenChange, onComplete])
const goPrev = React.useCallback(() => {
if (!isFirst) setCurrentStep((s) => s - 1)
}, [isFirst])
React.useEffect(() => {
if (!open) return
function handleKeyDown(e: KeyboardEvent) {
if (e.key === "ArrowRight") goNext()
else if (e.key === "ArrowLeft") goPrev()
}
window.addEventListener("keydown", handleKeyDown)
return () => window.removeEventListener("keydown", handleKeyDown)
}, [open, goNext, goPrev])
if (!step) return null
return (
<DialogPrimitive.Root open={open} onOpenChange={onOpenChange}>
<DialogPrimitive.Portal>
<DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0" />
<DialogPrimitive.Content
className="fixed left-1/2 top-1/2 z-50 w-[90vw] max-w-2xl -translate-x-1/2 -translate-y-1/2 overflow-hidden rounded-2xl border border-border bg-card data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95"
>
<div
className={cn(
"grid",
step.image ? "md:grid-cols-[1fr_1fr]" : "",
)}
>
<div className="flex flex-col justify-between p-6 md:p-8">
<div>
<div className="mb-5 flex items-center gap-2">
{steps.map((_, i) => (
<button
key={i}
type="button"
onClick={() => setCurrentStep(i)}
className={cn(
"size-2.5 cursor-pointer rounded-full transition-all duration-200",
i === currentStep
? "scale-125 bg-primary"
: "bg-zinc-300 hover:bg-zinc-400 dark:bg-zinc-600 dark:hover:bg-zinc-500",
)}
aria-label={`Step ${i + 1}`}
/>
))}
</div>
<h2 className="text-xl font-semibold tracking-tight text-foreground">
{step.title}
</h2>
<p className="mt-2 text-sm leading-relaxed text-muted-foreground">
{step.description}
</p>
</div>
<div className="mt-8 flex items-center gap-3">
{!isFirst ? (
<Button
variant="outline"
onClick={goPrev}
className="min-w-[100px]"
>
{previousLabel}
</Button>
) : null}
<Button
onClick={goNext}
className="min-w-[100px]"
>
{isLast ? doneLabel : nextLabel}
</Button>
</div>
</div>
{step.image ? (
<div className="hidden items-center justify-center bg-zinc-100 p-6 dark:bg-zinc-900 md:flex">
{step.image}
</div>
) : null}
</div>
</DialogPrimitive.Content>
</DialogPrimitive.Portal>
</DialogPrimitive.Root>
)
}
export { GuidedTour }
export type { GuidedTourStep, GuidedTourProps }
Preview