Spotlight

The zero-dependency site tour engine for modern web apps.
Direct user focus with declarative HTML annotations, fluid SVG cutout morphing, and adaptive theming.

Explore Live Playground → · Read Documentation → · Why Spotlight? · Report Issue →

Traditional onboarding libraries force you to manage detached 200-line JSON config arrays paired with brittle CSS selectors (.btn-primary > div:first-child). The second a teammate refactors a class name, the tour silently breaks.

Spotlight flips this model: your DOM elements declare their own tour steps in-place using native data-spot-* attributes.

• Zero External Dependencies — Written in pure TypeScript with lightweight hardware-accelerated SVG (~25KB gzipped).
• 100% Declarative Markup — Annotate elements directly with data-spot-name, data-spot-summary, and data-spot-media.
• Fluid Cutout Morphing — Smooth cubic-bezier transitions glide between target elements of any shape or size.
• Collision-Aware Positioning — Auto-flips (top, bottom, left, right) with boundary clamping and dynamically tethered arrows.
• Rich Media Embeds — Seamlessly renders looping MP4/WebM videos, animated GIFs, or responsive images in popovers.
• Adaptive Theme Engine — Real-time 'auto' (system sync), 'dark', and 'light' color modes.
• Universal & SSR-Safe — Works out-of-the-box with React, Next.js, Vue, Svelte, Astro, or via esm.sh in plain HTML.
• Production Proven — Built and dogfooded across production dashboards at Dotix.

Install via your preferred package manager:

npm install @cttricks/spotlight
# or: pnpm add @cttricks/spotlight | yarn add @cttricks/spotlight | bun add @cttricks/spotlight

<!-- Include Stylesheet -->
<link rel="stylesheet" href="https://esm.sh/@cttricks/spotlight/dist/styles/spotlight.css">

<!-- Import & Start -->
<script type="module">
  import { spotlight } from 'https://esm.sh/@cttricks/spotlight';
  const tour = await spotlight();
  tour.start();
</script>

<button 
  data-spot-id="search-btn"
  data-spot-name="Instant Search" 
  data-spot-summary="Press ⌘K anytime to search documents and shortcuts."
  data-spot-media="/assets/search-preview.mp4"
  data-spot-position="bottom">
  Search (⌘K)
</button>

import { spotlight } from '@cttricks/spotlight';
import '@cttricks/spotlight/styles';

const tour = await spotlight({
  theme: 'auto',              // 'light' | 'dark' | 'auto' (OS color sync)
  highlightColor: '#ffffff',  // Custom stroke & accent color
  backdropBlur: 4             // Glassmorphism backdrop blur (px)
});

tour.start();

tour.start();            // Start tour from step 1
tour.start({ from: 2 }); // Start from specific step ID or index
tour.next();             // Advance to next step
tour.previous();         // Return to previous step
tour.goTo(3);            // Jump directly to step index
tour.end();              // Close the active tour
tour.setTheme('dark');   // Switch theme live ('light' | 'dark' | 'auto')
tour.destroy();          // Unbind all event listeners and remove DOM overlay

Need multi-tour flows? Tag elements with data-spot-group="billing" and launch isolated sequences using tour.start({ group: 'billing' }).

Spotlight ships with a built-in agent skill specification (SKILL.md).

When using Claude Code, Cursor, Codex, or Antigravity in your project, simply prompt your agent:

"Read node_modules/@cttricks/spotlight/SKILL.md and implement an onboarding tour for our dashboard."

The agent will automatically know all declarative data-spot-* attributes, SSR safeguards, and framework recipes without guessing.

Detailed specifications, API references, and framework recipes are organized in the docs/ directory:

Tweak highlight strokes, cutout radiuses, backdrop opacities, and animation timings in real-time on our official showcase:

👉 spotlight.cttricks.com

Contributions, issues, and feature requests are welcome!

• See Contribution.md for local development setup.
• File bug reports and proposals on GitHub Issues.

AI Disclosure 🤖

This project was developed with the assistance of Antigravity. I used it to improve and refine the library, while the playground/demo-site were completely generated by Antigravity.

— Tanish

MIT © Tanish Raj