simple-spotlight

Tiny React component to highlight any UI element. Zero dependencies, under 3kb.

Perfect for feature announcements, onboarding hints, and new feature discovery — without pulling in a massive tour library.

Install

npm install simple-spotlight

Usage

import { useState } from "react";
import { Spotlight } from "simple-spotlight";

function App() {
  const [show, setShow] = useState(true);

  return (
    <Spotlight
      active={show}
      label="New Feature"
      description="Check out what's new."
      placement="bottom"
      onDismiss={() => setShow(false)}
    >
      <button>New feature</button>
    </Spotlight>
  );
}

That's it. Wrap any element, pass active={true}, done.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | active | boolean | false | Show or hide the spotlight | | label | string | "" | Bold tooltip heading | | description | string | "" | Tooltip body text | | pulse | boolean | true | Animate the glow ring | | placement | "top" \| "bottom" \| "left" \| "right" | "bottom" | Tooltip position | | onDismiss | () => void | — | Called when user clicks dismiss | | overlayColor | string | "rgba(0,0,0,0.55)" | Overlay background | | accentColor | string | "#6EE7B7" | Glow and button color | | dismissText | string | "Got it" | Dismiss button label | | showDismiss | boolean | true | Show dismiss button |

Multiple Spotlights

Each spotlight just needs its own state:

const [showFeature1, setShowFeature1] = useState(true);
const [showFeature2, setShowFeature2] = useState(false);

<Spotlight active={showFeature1} label="New!" onDismiss={() => {
  setShowFeature1(false);
  setShowFeature2(true); // chain to next
}}>
  <Button>Feature 1</Button>
</Spotlight>

<Spotlight active={showFeature2} label="Also new!" onDismiss={() => setShowFeature2(false)}>
  <Button>Feature 2</Button>
</Spotlight>

How It Works

1. Wraps child with a ref via useRef
2. On active, calls getBoundingClientRect() to measure position
3. Renders SVG overlay with <mask> cutout around the element
4. Positions tooltip based on placement + measured rect
5. Listens to resize / scroll for live repositioning

Why This Instead of Shepherd.js / Intro.js?

• ~2.8kb gzip vs 40kb+
• No config files, no steps array, no CSS imports
• Just wrap a component — works anywhere in your tree
• TypeScript support out of the box

License

MIT