Onboarding Tour Spotlight
Product tour that dims the page except a spotlight cutout, morphs the cutout from target to target, and floats a tooltip card with Back, Next and Skip.
About This Component
A first-run tour for an app: the page dims, one control stays fully lit inside a spotlight cut out of the dim, and a tooltip card explains it. Next and Back morph the cutout to the next target, tweening its position and size at once so it reads as one shape travelling rather than a box being redrawn, and the card follows to whichever side has room.
Read the full effect overview
The steps are an array of a selector and two strings, so a tour is configuration rather than markup. Escape ends it, focus moves into the card and stays there, and a resize re-measures every target. Ships in three looks, vault, glass and corporate, switched by one data-variant attribute. One HTML file, one stylesheet, one script, core GSAP only.
What's Included
- Spotlight is a hole in an SVG mask, so the highlighted control stays at full contrast
- Cutout morphs position and size together on power3.inOut
- Tooltip card follows the spotlight and flips above the target when there is no room below
- Steps are a plain array of selector, title and body
- Escape ends the tour, arrow keys move between steps, focus is held in the card
- Resize and scroll re-measure the current target and snap the spotlight to it
- Ring drawn around the cutout in the variant accent
- No JavaScript simply leaves the app usable with no tour
- Three shipped variants: vault, glass, corporate
Perfect For
- First-run onboarding in a dashboard or admin console
- Feature announcements pointing at the control that changed
- Guided walkthroughs in documentation and demos
- In-app help that highlights the step a user is stuck on
How It Works
A hole in the dim
The overlay is one SVG: a full-size rect filled with the variant's dim colour, masked by a white rect with a black rounded rect punched through it. Black in a mask means fully transparent, so the target underneath keeps its own colours at full contrast instead of sitting behind a lightened patch, which is what a second stacked overlay would give you.
Morphing between targets
Each step measures its target with getBoundingClientRect, adds the variant's padding, and tweens the mask rect's x, y, width, height and corner radius in a single attr tween on power3.inOut. The ring rect is tweened in the same call, so the outline and the hole can never drift apart mid-travel.
Card placement and focus
The card is positioned with x and y from GSAP and carries no CSS transform, so its measured position is never added to twice. It prefers the space below the spotlight, flips above when the viewport is short, and is clamped to a margin from every edge. Opening moves focus to Next, a keydown handler cycles Tab inside the card, Escape ends the tour, and focus returns to whatever opened it.