{[
["Top referrer", "news.ycombinator.com", "31% of visits"],
["Top country", "United States", "42% of visits"],
["Top device", "Desktop", "68% of visits"],
["Top browser", "Chrome", "57% of visits"],
].map(([label, value, note]) => (
{label}
{value}
{note}
))}
Top pages
{pages.map((page) => (
{page.path}
{page.views}
{page.change}
))}
);
}
```
### Form Help
A sign-up form that explains each field in turn. You can type into each field while it's highlighted.
Install this demo, with the component included:
```bash
npx shadcn@latest add @keyframeui/spotlight-tour-form-demo
```
```tsx title="components/spotlight-tour-form-demo.tsx"
"use client";
import * as React from "react";
import { SpotlightTour, type SpotlightTourStep } from "@/components/ui/spotlight-tour";
// Each field stays typable while it's highlighted.
const steps: SpotlightTourStep[] = [
{
target: "[data-tour=signup-name]",
title: "Your name",
body: "This is how teammates see you in comments and mentions.",
side: "right",
padding: 6,
interactive: true,
},
{
target: "[data-tour=signup-email]",
title: "Use your work email",
body: "So teammates can find you, and you join your company's workspace automatically.",
side: "right",
padding: 6,
interactive: true,
},
{
target: "[data-tour=signup-password]",
title: "Pick a password",
body: "At least 12 characters. A short sentence is easier to remember than symbols.",
side: "right",
padding: 6,
interactive: true,
},
{
target: "[data-tour=signup-workspace]",
title: "Name your workspace",
body: "It becomes your address. You can change it later in settings.",
side: "right",
padding: 6,
interactive: true,
},
{
target: "[data-tour=signup-submit]",
title: "You're ready",
body: "Create the workspace, then invite your team on the next screen.",
side: "right",
padding: 6,
},
];
function strength(password: string) {
let score = 0;
if (password.length >= 8) score++;
if (password.length >= 12) score++;
if (/[A-Z]/.test(password) && /[a-z]/.test(password)) score++;
if (/[\d\s\W]/.test(password)) score++;
return password ? Math.max(score, 1) : 0;
}
const meter = ["", "bg-rose-500", "bg-amber-500", "bg-lime-500", "bg-emerald-500"];
const field =
"h-10 w-full rounded-lg bg-white px-3 text-sm text-zinc-900 ring-1 ring-zinc-900/10 transition-shadow outline-none placeholder:text-zinc-400 focus:ring-2 focus:ring-zinc-900 dark:bg-zinc-950 dark:text-zinc-50 dark:ring-white/10 dark:focus:ring-zinc-100";
const label = "mb-1.5 block text-sm font-medium text-zinc-900 dark:text-zinc-100";
export function SpotlightTourFormDemo() {
const [open, setOpen] = React.useState(false);
const [password, setPassword] = React.useState("");
const [workspace, setWorkspace] = React.useState("");
const [visible, setVisible] = React.useState(false);
const [created, setCreated] = React.useState(false);
const score = strength(password);
React.useEffect(() => {
if (!created) return;
const timer = window.setTimeout(() => setCreated(false), 2200);
return () => window.clearTimeout(timer);
}, [created]);
return (
Create your workspace
Free for teams of up to 5.
);
}
```
## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `SpotlightTourStep[]` | | The stops on the tour. Each has a `title`, and optionally a `body`, a `target` (a CSS selector, an element or a ref; leave it out for a centered card with no highlight), a `side` for the card, its own `padding` and `radius`, `interactive` to let people click and type inside the hole, and `advanceOnClick` to move on when the element is clicked. |
| `open` (required) | `boolean` | | Whether the tour is showing. |
| `onOpenChange` | `(open: boolean) => void` | | Called with `false` when the tour is skipped, closed with Esc or finished. |
| `step` | `number` | | The current step, to control it yourself. Otherwise the tour starts at the first step each time it opens. |
| `onStepChange` | `(step: number) => void` | | Called when the step changes. Use it to get the page ready, such as opening a menu before highlighting something inside it. The tour waits for the element to appear. |
| `onComplete` | `() => void` | | Called when Done is pressed on the last step, not when the tour is skipped. |
| `padding` | `number` | `8` | Room between each element and the edge of its hole, in pixels. A step's own `padding` wins. |
| `className` | `string` | | Extra classes for the card. |
| `overlayClassName` | `string` | | Extra classes for the dimmed layer, such as its color. Defaults to `bg-black/50 dark:bg-black/65`. |
## Source
```tsx title="components/ui/spotlight-tour.tsx"
"use client";
import * as React from "react";
import {
AnimatePresence,
animate,
cancelFrame,
frame,
motion,
useMotionValue,
useReducedMotion,
type Variants,
} from "motion/react";
import { cn } from "@/lib/utils";
/* ─────────────────────────────────────────────────────────
* SPOTLIGHT TOUR STORYBOARD
*
* open the page dims, then a hole irises open out of the
* dark around the first element and the card rises
* in beside it
* next the hole glides to the next element on a spring
* and takes its shape: round for an avatar, a long
* pill for a toolbar, a rounded panel for a sidebar.
* The card rides along, moving to another side when
* it has to, and its text slides over to the new step
* scroll an element out of view scrolls in on the same
* spring the hole travels on, so it's one motion
* arrive one soft ring pulses out from the hole
* redirect press again mid-flight and it bends toward the new
* element without stopping
* stay scrolling, resizing and layout shifts keep the hole
* on its element
* finish the hole widens past the edges of the screen as the
* dark lifts, and the card fades away
* ───────────────────────────────────────────────────────── */
const TOUR = {
open: { type: "spring", visualDuration: 0.5, bounce: 0.2, delay: 0.12 }, // the iris on the first step
travel: { type: "spring", visualDuration: 0.5, bounce: 0.14 },
close: { type: "spring", visualDuration: 0.6, bounce: 0 },
resize: { type: "spring", visualDuration: 0.32, bounce: 0.04 }, // the card's height following its text
dots: { type: "spring", visualDuration: 0.4, bounce: 0.24 },
pulse: { duration: 0.9, ease: [0.22, 1, 0.36, 1] },
dimIn: { duration: 0.3, ease: "easeOut" },
dimOut: { duration: 0.45, ease: [0.55, 0, 0.75, 0.4] }, // lingers, then lifts, so the iris reads
cardIn: { duration: 0.32, ease: [0.22, 1, 0.36, 1], delay: 0.2 },
fadeOut: { duration: 0.16, ease: "easeOut" },
padding: 8, // px between an element and the edge of its hole
gap: 14, // px between the hole and the card; the arrow sits in it
margin: 12, // px kept clear of the viewport edges
wait: 1500, // ms to wait for a step's element to appear
} as const;
const DIM = "bg-black/50 dark:bg-black/65";
export interface SpotlightTourStep {
/** The element to highlight: a CSS selector, an element or a ref. Leave it out for a step with no highlight. */
target?: string | Element | React.RefObject | null;
title: React.ReactNode;
body?: React.ReactNode;
/** Side of the element the card sits on. Defaults to the side with the most room. */
side?: "top" | "right" | "bottom" | "left";
/** Room between the element and the edge of the hole, in px. */
padding?: number;
/** Corner radius of the hole, in px. Defaults to the element's own, plus the padding. */
radius?: number;
/** Let people click and type inside the hole. */
interactive?: boolean;
/** Go to the next step when the element is clicked. The click still reaches it. */
advanceOnClick?: boolean;
}
export interface SpotlightTourProps {
steps: SpotlightTourStep[];
open: boolean;
onOpenChange?: (open: boolean) => void;
/** The current step, to control it yourself. Otherwise the tour starts at the first step each time it opens. */
step?: number;
onStepChange?: (step: number) => void;
/** Called when Done is pressed on the last step, not when the tour is skipped. */
onComplete?: () => void;
/** Default room around each element, in px. */
padding?: number;
/** Classes for the card. */
className?: string;
/** Classes for the dimmed layer, e.g. its color. */
overlayClassName?: string;
}
type Side = NonNullable;
type Placement = Side | "center";
type Point = { x: number; y: number };
type Size = { width: number; height: number };
type Radii = [number, number, number, number]; // top-left, top-right, bottom-right, bottom-left
type Hole = Point & Size & { radii: Radii };
type Corner = { px: number; pct: number };
type ScrollMove = { element: Element; axis: "x" | "y"; from: number; to: number };
type Thenable = { then: (onResolve: () => void) => unknown };
type View = Size & { bottom: number }; // `bottom` is the visible bottom edge, above an on-screen keyboard
type Flight = {
// Where the trip started. The start rides along with the element it
// left, so a page scrolling under it carries it too.
anchor: Element | null;
anchorAt: Point;
shift: Point;
hole: Hole;
card: Point | null; // null: the card starts where it ends
side: Placement;
};
const ORIGIN: Point = { x: 0, y: 0 };
// Covers the screen. The hole is cut out of it with the even-odd rule.
const OUTSIDE = "M-99999 -99999H99999V99999H-99999Z";
export function SpotlightTour({
steps,
open,
onOpenChange,
step,
onStepChange,
onComplete,
padding = TOUR.padding,
className,
overlayClassName,
}: SpotlightTourProps) {
const id = React.useId();
const reduceMotion = useReducedMotion() ?? false;
const [mounted, setMounted] = React.useState(false);
const [ownIndex, setOwnIndex] = React.useState(0);
const count = steps.length;
const index = clamp(step ?? ownIndex, 0, Math.max(count - 1, 0));
// Which way the text slides: forward or back.
const [paged, setPaged] = React.useState({ index, direction: 1 });
if (paged.index !== index) setPaged({ index, direction: index > paged.index ? 1 : -1 });
const direction = paged.direction;
const current = steps[index];
const last = index === count - 1;
const passThrough = passThroughFor(current);
const layerRef = React.useRef(null);
const dimRef = React.useRef(null);
const plugRef = React.useRef(null);
const blockerRef = React.useRef(null);
const outlineRef = React.useRef(null);
const ringRef = React.useRef(null);
const cardRef = React.useRef(null);
const arrowRef = React.useRef(null);
const bodyRef = React.useRef(null);
const contentRef = React.useRef(null);
const live = React.useRef({
phase: "closed" as "closed" | "open" | "closing",
index: 0,
started: false, // the first trip, which irises open, has begun
trip: 0, // bumps with every trip, so a stale trip's callbacks do nothing
generation: 0, // bumps on every open and close
target: null as Element | null,
corners: null as Corner[] | null,
waiting: 0, // when we began looking for the step's element; 0 when not looking
flight: null as Flight | null,
side: "center" as Placement, // the card's side for this step
drawnSide: "center" as Placement, // the side its arrow is on right now
hole: zeroHole(ORIGIN),
lastEnd: null as Hole | null,
exit: null as Hole | null,
card: ORIGIN,
drive: [] as ScrollMove[],
arrived: false,
resting: false,
bodyTarget: 0,
chrome: 0, // the card's height without its text
velocity: [0, 0, 0, 0], // the hole's x, y, width and height speeds, px/s
time: 0,
reduce: false,
wide: null as MediaQueryList | null,
returnFocus: null as HTMLElement | null,
});
const progress = useMotionValue(0); // 0 where a trip starts, 1 where it ends
const veil = useMotionValue(0); // the dim
const shown = useMotionValue(0); // the card
const plug = useMotionValue(0); // fills the hole, to fade between steps with reduced motion
const pulse = useMotionValue(0);
const bodyHeight = useMotionValue(0);
// ── Trips ───────────────────────────────────────────────
// A trip that ran its course: stop driving the scroll.
const settle = (run: Thenable, trip: number) => {
run.then(() => {
const s = live.current;
if (s.trip !== trip) return;
s.drive = [];
s.resting = true;
});
};
const depart = (target: Element | null, options: { quiet?: boolean; scroll?: boolean } = {}) => {
const s = live.current;
const config = steps[s.index];
if (!config) return;
const view = viewport();
const docked = !s.wide?.matches;
const opening = !s.started;
const trip = ++s.trip;
const previous = s.target;
const pad = config.padding ?? padding;
s.started = true;
s.waiting = 0;
s.target = target;
s.corners = target ? readCorners(target) : null;
s.lastEnd = null;
s.arrived = !!options.quiet;
s.resting = false;
// Bring the element into view, clear of the card when it's docked.
const cardHeight = s.chrome + s.bodyTarget;
const moves =
target && options.scroll !== false
? planScroll(target, pad, docked ? cardHeight + TOUR.margin * 2 : 0, view)
: [];
const offset = { x: 0, y: 0 };
for (const move of moves) offset[move.axis] += move.to - move.from;
// Where the element will be once that's done picks the card's side.
const now = target && s.corners ? holeAround(target, s.corners, pad, config.radius) : null;
const end = now ? moveHole(now, -offset.x, -offset.y) : null;
const width = cardRef.current?.offsetWidth ?? 320;
s.side = chooseSide(end, config.side, { width, height: cardHeight }, view);
if (opening) {
// Nothing is on screen yet, so with reduced motion it can just jump.
if (s.reduce) for (const move of moves) scrollMove(move, move.to);
s.drive = s.reduce ? [] : moves;
s.flight =
target && now && !s.reduce
? { anchor: target, anchorAt: topLeft(target) ?? ORIGIN, shift: ORIGIN, hole: collapse(now), card: null, side: s.side }
: null;
progress.jump(s.reduce ? 1 : 0);
animate(shown, 1, s.reduce ? TOUR.dimIn : TOUR.cardIn);
if (s.reduce) s.resting = true;
else settle(animate(progress, 1, TOUR.open), trip);
return;
}
const anchor = previous && topLeft(previous) ? previous : null;
s.flight = {
anchor,
anchorAt: (anchor && topLeft(anchor)) || ORIGIN,
shift: ORIGIN,
hole: s.hole,
card: s.card,
side: s.drawnSide,
};
progress.jump(0);
if (s.reduce) {
// Fade the hole shut, move, then fade it open on the new element.
s.drive = [];
animate(plug, 1, { duration: 0.12, ease: "easeOut" }).then(() => {
if (s.trip !== trip) return;
for (const move of moves) scrollMove(move, move.to);
s.flight = null;
progress.jump(1);
s.resting = true;
animate(plug, 0, { duration: 0.2, ease: "easeOut" });
});
return;
}
// Carry the hole's speed into the new trip, so pressing again
// mid-flight bends its path instead of stopping it dead.
const goal = end ?? collapse(s.hole);
const path = [goal.x - s.hole.x, goal.y - s.hole.y, goal.width - s.hole.width, goal.height - s.hole.height];
const length = dot(path, path);
const velocity = length > 1 ? clamp(dot(s.velocity, path) / length, -2, 8) : 0;
s.drive = moves;
settle(animate(progress, 1, { ...TOUR.travel, velocity }), trip);
};
// Head for the current step's element, or wait for it to appear.
const seek = () => {
const s = live.current;
const config = steps[s.index];
if (!config) return;
if (!config.target) return depart(null);
const element = resolve(config.target);
if (element && topLeft(element)) depart(element);
else s.waiting = performance.now();
};
// ── Open and close ──────────────────────────────────────
const start = () => {
const s = live.current;
if (!steps.length || s.phase === "open") return;
if (s.phase === "closing") {
// Opened again on the way out: close back in on the step.
s.phase = "open";
s.generation++;
s.exit = null;
animate(veil, 1, TOUR.dimIn);
animate(shown, 1, TOUR.dimIn);
cardRef.current?.focus({ preventScroll: true });
seek();
return;
}
const view = viewport();
s.phase = "open";
s.generation++;
s.started = false;
s.target = null;
s.corners = null;
s.flight = null;
s.exit = null;
s.waiting = 0;
s.drive = [];
s.side = "center";
s.drawnSide = "center";
s.hole = zeroHole({ x: view.width / 2, y: view.height / 2 });
s.velocity = [0, 0, 0, 0];
s.reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
s.wide = window.matchMedia("(min-width: 40rem)");
s.returnFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
progress.jump(0);
veil.jump(0);
shown.jump(0);
plug.jump(0);
pulse.jump(0);
if (step === undefined) setOwnIndex(0);
setMounted(true);
};
const close = () => {
const s = live.current;
if (s.phase !== "open") return;
s.phase = "closing";
s.waiting = 0;
s.drive = [];
s.trip++;
const generation = ++s.generation;
const runs: Thenable[] = [animate(shown, 0, TOUR.fadeOut)];
if (s.reduce) {
runs.push(animate(veil, 0, TOUR.dimIn));
} else {
// The hole widens past the edges of the screen as the dark lifts.
const anchor = s.target && topLeft(s.target) ? s.target : null;
s.flight = {
anchor,
anchorAt: (anchor && topLeft(anchor)) || ORIGIN,
shift: ORIGIN,
hole: s.hole,
card: s.card,
side: s.drawnSide,
};
s.exit = widen(s.hole, viewport());
progress.jump(0);
// Once the dark is gone the rest of the widening can't be seen, so
// the layer goes away then, without waiting for the spring to rest.
animate(progress, 1, TOUR.close);
runs.push(animate(veil, 0, TOUR.dimOut));
}
// The page is usable straight away: hand focus back now.
const layer = layerRef.current;
const focus = document.activeElement;
if ((!focus || focus === document.body || layer?.contains(focus)) && s.returnFocus?.isConnected) {
s.returnFocus.focus({ preventScroll: true });
}
Promise.all(runs).then(() => {
if (live.current.generation === generation) finish();
});
};
// Gone: put the layer away.
const finish = () => {
const s = live.current;
if (s.phase !== "closing") return;
s.phase = "closed";
s.target = null;
s.flight = null;
s.exit = null;
const layer = layerRef.current;
if (layer?.matches(":popover-open")) layer.hidePopover();
setMounted(false);
};
const go = (to: number) => {
const s = live.current;
if (s.phase !== "open" || to < 0 || to === s.index) return;
if (to >= steps.length) {
onComplete?.();
onOpenChange?.(false);
return;
}
if (step === undefined) setOwnIndex(to);
onStepChange?.(to);
};
const skip = () => onOpenChange?.(false);
const clicked = (event: MouseEvent) => {
const s = live.current;
if (s.phase !== "open" || !steps[s.index]?.advanceOnClick || !s.target) return;
if (event.target instanceof Node && s.target.contains(event.target)) go(s.index + 1);
};
// A click on the dark: pulse the ring again to point at the element.
const nudge = (event: React.PointerEvent) => {
const s = live.current;
if (!event.isPrimary || s.phase !== "open" || s.reduce || !s.target) return;
pulse.jump(0);
animate(pulse, 1, TOUR.pulse);
};
// Tab moves through the card and, on interactive steps, the element.
const cycleFocus = (event: KeyboardEvent) => {
const s = live.current;
const card = cardRef.current;
const config = steps[s.index];
if (!card) return;
const inside = passThroughFor(config) && s.target ? focusables(s.target) : [];
const items = [...inside, ...focusables(card)];
if (!items.length) return;
event.preventDefault();
const at = items.indexOf(document.activeElement as HTMLElement);
const next =
at === -1
? event.shiftKey
? items.length - 1
: 0
: (at + (event.shiftKey ? -1 : 1) + items.length) % items.length;
items[next].focus({ preventScroll: true });
};
const measureCard = () => {
const s = live.current;
const card = cardRef.current;
const body = bodyRef.current;
const content = contentRef.current;
if (!card || !body || !content) return;
s.chrome = card.offsetHeight - body.offsetHeight;
const height = content.offsetHeight;
if (s.started && Math.abs(height - s.bodyTarget) < 0.5) return;
s.bodyTarget = height;
if (!s.started || s.reduce) bodyHeight.jump(height);
else animate(bodyHeight, height, TOUR.resize);
};
// ── Every frame ─────────────────────────────────────────
const tick = () => {
const s = live.current;
const dim = dimRef.current;
const plugElement = plugRef.current;
const blocker = blockerRef.current;
const outline = outlineRef.current;
const ring = ringRef.current;
const card = cardRef.current;
const arrow = arrowRef.current;
const body = bodyRef.current;
if (s.phase === "closed" || !dim || !plugElement || !blocker || !outline || !ring || !card || !arrow || !body) {
return;
}
const config = steps[s.index];
const view = viewport();
const docked = !s.wide?.matches;
const width = card.offsetWidth;
// A step whose element hasn't appeared yet: keep looking, for a while.
if (s.waiting && config) {
const element = resolve(config.target);
if (element && topLeft(element)) depart(element);
else if (performance.now() - s.waiting > TOUR.wait) depart(null);
}
// The element was swapped for a new one, as re-renders can do: follow it.
if (s.target && !s.target.isConnected && config) {
const element = resolve(config.target);
if (element && element !== s.target && topLeft(element)) {
s.target = element;
s.corners = readCorners(element);
}
}
const p = progress.get();
for (const move of s.drive) scrollMove(move, lerp(move.from, move.to, clamp(p, 0, 1)));
// The hole runs from where the trip started to the element it's headed for.
const f = s.flight;
if (f?.anchor) {
const at = topLeft(f.anchor);
if (at) f.shift = { x: at.x - f.anchorAt.x, y: at.y - f.anchorAt.y };
}
const start = f ? moveHole(f.hole, f.shift.x, f.shift.y) : null;
let end: Hole;
if (s.phase === "closing" && s.exit) {
end = s.exit;
} else if (s.target && s.corners && config) {
const measured = holeAround(s.target, s.corners, config.padding ?? padding, config.radius);
if (measured) s.lastEnd = measured;
end = measured ?? s.lastEnd ?? s.hole;
} else {
end = collapse(start ?? s.hole);
}
const hole = start ? mixHole(start, end, p) : end;
const holeOpen = hole.width > 1 && hole.height > 1;
const time = performance.now();
const dt = (time - s.time) / 1000;
s.velocity =
dt > 0.001 && dt < 0.1
? [(hole.x - s.hole.x) / dt, (hole.y - s.hole.y) / dt, (hole.width - s.hole.width) / dt, (hole.height - s.hole.height) / dt]
: [0, 0, 0, 0];
s.time = time;
s.hole = hole;
// The card rides along, from where it was to beside the element.
const size = { width, height: s.chrome + bodyHeight.get() };
let side = s.side;
let arrowOpacity = 1;
if (s.phase === "open") {
if (docked) {
s.card = { x: (view.width - width) / 2, y: view.bottom - TOUR.margin - size.height };
} else {
const goal = placeCard(s.side === "center" ? null : end, s.side, size, view);
s.card = f?.card ? mixPoint(movePoint(f.card, f.shift), goal, p) : goal;
}
// Changing sides: the arrow fades out on the old one, then in on the new.
if (f?.card && f.side !== s.side) {
if (p < 0.5) {
side = f.side;
arrowOpacity = 1 - p * 2;
} else arrowOpacity = Math.min(p * 2 - 1, 1);
}
s.drawnSide = side;
}
// Pulse once on arrival.
if (s.phase === "open" && !s.arrived && s.target && p >= 0.96) {
s.arrived = true;
if (!s.reduce) {
pulse.jump(0);
animate(pulse, 1, TOUR.pulse);
}
}
// Draw.
const dark = veil.get();
const plugged = plug.get();
const active = s.phase === "open";
write(dim, {
clipPath: `path(evenodd, "${OUTSIDE}${holePath(hole)}")`,
opacity: str(dark),
pointerEvents: active ? "auto" : "none",
});
write(blocker, { ...boxStyle(hole), pointerEvents: active && !passThroughFor(config) ? "auto" : "none" });
write(outline, { ...boxStyle(hole), opacity: holeOpen ? str(dark) : "0" });
write(plugElement, { ...boxStyle(hole), opacity: holeOpen ? str(plugged) : "0" });
const q = pulse.get();
write(
ring,
q > 0 && q < 1 && holeOpen && active
? { ...boxStyle(growHole(hole, 2 + q * 12)), opacity: str((1 - q) * 0.75 * dark) }
: { opacity: "0" },
);
const presence = shown.get();
const showArrow = active && !docked && side !== "center" && holeOpen;
const tip = showArrow ? arrowAt(hole, side as Side, s.card, size) : null;
const lift = s.reduce
? ""
: docked
? `translateY(${num((1 - presence) * 20)}px)`
: `scale(${num(0.94 + 0.06 * presence)})`;
write(card, {
transform: `translate3d(${num(s.card.x)}px, ${num(s.card.y)}px, 0) ${lift}`,
opacity: str(presence * (1 - plugged)),
pointerEvents: active ? "auto" : "none",
...(active ? { transformOrigin: tip ? `${num(tip.x)}px ${num(tip.y)}px` : "50% 50%" } : null),
});
write(body, { height: `${num(bodyHeight.get())}px` });
if (active) {
write(
arrow,
tip
? { transform: `translate(${num(tip.x - 8)}px, ${num(tip.y - 8)}px) rotate(${tip.rotate}deg)`, opacity: str(arrowOpacity) }
: { opacity: "0" },
);
}
// At rest, with the card squeezed out of its side (the page scrolled,
// or the window shrank): move it to a side that has room.
if (active && s.resting && !docked && s.target && s.side !== "center" && config) {
const need = { width, height: s.chrome + s.bodyTarget };
const room = roomAround(end, need, view);
if (room[s.side] < 0) {
const better = chooseSide(end, config.side, need, view);
if (better !== s.side && better !== "center" && room[better] >= 0) {
depart(s.target, { quiet: true, scroll: false });
}
}
}
};
// Global listeners and the frame loop call the latest versions of these.
const actions = React.useRef({ start, close, go, skip, clicked, tick, measureCard, seek, cycleFocus });
React.useLayoutEffect(() => {
actions.current = { start, close, go, skip, clicked, tick, measureCard, seek, cycleFocus };
});
React.useEffect(() => {
if (open) actions.current.start();
else actions.current.close();
}, [open]);
// Mounted: lift the layer into the top layer, move focus to the card and
// start drawing.
React.useLayoutEffect(() => {
const layer = layerRef.current;
if (!mounted || !layer) return;
if (!layer.matches(":popover-open")) {
layer.popover = "manual";
layer.showPopover();
}
cardRef.current?.focus({ preventScroll: true });
animate(veil, 1, TOUR.dimIn);
const draw = () => actions.current.tick();
frame.render(draw, true);
return () => cancelFrame(draw);
}, [mounted, veil]);
// Each step: size the card to its text, then head for the step's element.
React.useLayoutEffect(() => {
if (!mounted) return;
const s = live.current;
const fresh = s.index !== index || !s.started;
s.index = index;
actions.current.measureCard();
if (fresh && s.phase === "open") actions.current.seek();
// Keep focus in the card, say when the button that had it went away.
const card = cardRef.current;
const focus = document.activeElement;
if (card && !card.contains(focus) && !(passThrough && s.target?.contains(focus))) {
card.focus({ preventScroll: true });
}
}, [mounted, index, passThrough]);
// The card's height follows its text.
React.useLayoutEffect(() => {
const content = contentRef.current;
if (!mounted || !content) return;
const observer = new ResizeObserver(() => actions.current.measureCard());
observer.observe(content);
return () => observer.disconnect();
}, [mounted]);
React.useEffect(() => {
if (!mounted) return;
const onKeyDown = (event: KeyboardEvent) => {
const s = live.current;
if (s.phase !== "open" || event.defaultPrevented || event.isComposing) return;
if (event.key === "Escape") {
event.preventDefault();
actions.current.skip();
return;
}
if (event.key === "Tab") {
actions.current.cycleFocus(event);
return;
}
// Arrows and Enter steer the tour only from the card, so they still
// type and pick inside an interactive element.
const focus = document.activeElement;
const free = !focus || focus === document.body || !!cardRef.current?.contains(focus);
if (!free || event.repeat || event.metaKey || event.ctrlKey || event.altKey) return;
const onControl = focus instanceof Element && !!focus.closest("button, a[href], input, select, textarea");
if (event.key === "ArrowRight" || (event.key === "Enter" && !onControl)) {
event.preventDefault();
actions.current.go(s.index + 1);
} else if (event.key === "ArrowLeft") {
event.preventDefault();
actions.current.go(s.index - 1);
}
};
window.addEventListener("keydown", onKeyDown);
return () => window.removeEventListener("keydown", onKeyDown);
}, [mounted]);
// Steps that move on when their element is clicked.
React.useEffect(() => {
if (!mounted) return;
const onClick = (event: MouseEvent) => actions.current.clicked(event);
document.addEventListener("click", onClick);
return () => document.removeEventListener("click", onClick);
}, [mounted]);
// The wheel over the dark scrolls whatever is under it, nested scroll
// boxes included. Taking over the scroll stops the tour from driving it.
React.useEffect(() => {
const layer = layerRef.current;
if (!mounted || !layer) return;
const release = () => {
live.current.drive = [];
};
const onWheel = (event: WheelEvent) => {
if (event.ctrlKey) return; // pinch to zoom
event.preventDefault();
const scale = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? window.innerHeight : 1;
const dx = event.deltaX * scale;
const dy = event.deltaY * scale;
const under = document.elementsFromPoint(event.clientX, event.clientY).find((element) => !layer.contains(element));
scrollerFor(under ?? null, dx, dy).scrollBy({ left: dx, top: dy, behavior: "instant" });
};
window.addEventListener("wheel", release, { passive: true, capture: true });
window.addEventListener("touchstart", release, { passive: true, capture: true });
layer.addEventListener("wheel", onWheel, { passive: false });
return () => {
window.removeEventListener("wheel", release, { capture: true });
window.removeEventListener("touchstart", release, { capture: true });
layer.removeEventListener("wheel", onWheel);
};
}, [mounted]);
if (!mounted || !current) return null;
const button = cn(
"inline-flex h-8 cursor-pointer items-center justify-center rounded-full px-3 text-[13px] font-medium outline-none select-none [-webkit-tap-highlight-color:transparent]",
"transition-[background-color,color,scale] duration-150 ease-out active:scale-[0.97] motion-reduce:active:scale-100",
"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-foreground",
);
const text = reduceMotion ? FADE : SLIDE;
return (