@mshafiqyajid/react-spotlight

npm install @mshafiqyajid/react-spotlight

import { useRef, useState } from "react";
import { SpotlightStyled } from "@mshafiqyajid/react-spotlight/styled";
import "@mshafiqyajid/react-spotlight/styles.css";

function App() {
  const [open, setOpen] = useState(false);
  const btnRef = useRef<HTMLButtonElement>(null);

  return (
    <>
      <button ref={btnRef} onClick={() => setOpen(true)}>
        Show spotlight
      </button>

      <SpotlightStyled
        target={btnRef}
        open={open}
        onOpenChange={setOpen}
        placement="bottom"
      >
        <div>
          <strong>Welcome!</strong>
          <p>This button starts the tour.</p>
          <button onClick={() => setOpen(false)}>Got it</button>
        </div>
      </SpotlightStyled>
    </>
  );
}

import { useRef, useState } from "react";
import { SpotlightStyled } from "@mshafiqyajid/react-spotlight/styled";
import "@mshafiqyajid/react-spotlight/styles.css";
import type { SpotlightStep } from "@mshafiqyajid/react-spotlight";

function GuidedTour() {
  const [open, setOpen] = useState(false);
  const navRef    = useRef<HTMLElement>(null);
  const searchRef = useRef<HTMLElement>(null);
  const actionRef = useRef<HTMLElement>(null);

  const steps: SpotlightStep[] = [
    {
      target: navRef,
      placement: "right",
      content: <p>Use the sidebar to navigate between sections.</p>,
    },
    {
      target: searchRef,
      padding: 8,
      content: <p>Search anything from here.</p>,
    },
    {
      target: actionRef,
      placement: "bottom",
      content: <p>Create a new item with this button.</p>,
    },
  ];

  return (
    <>
      {/* ... your UI elements with the refs attached ... */}

      <button onClick={() => setOpen(true)}>Start tour</button>

      {/* SpotlightStyled renders prev/next/done nav automatically */}
      <SpotlightStyled
        target={navRef}
        open={open}
        onOpenChange={setOpen}
        steps={steps}
        pulse
      />
    </>
  );
}

const [currentStep, setCurrentStep] = useState(0);

<SpotlightStyled
  target={ref}
  open={open}
  onOpenChange={setOpen}
  steps={steps}
  step={currentStep}
  onStepChange={setCurrentStep}
/>

<SpotlightStyled target={ref} open={open} onOpenChange={setOpen} pulse>
  <p>Look here!</p>
</SpotlightStyled>

<SpotlightStyled
  target={ref}
  open={open}
  onOpenChange={setOpen}
  backdropBlur={8}
  overlayColor="rgba(0,0,0,0.4)"
>
  <p>Frosted glass overlay</p>
</SpotlightStyled>

<SpotlightStyled
  target="#my-nav-button"
  open={open}
  onOpenChange={setOpen}
>
  <p>This is the navigation button.</p>
</SpotlightStyled>

import { useRef } from "react";
import { SpotlightStyled } from "@mshafiqyajid/react-spotlight/styled";
import "@mshafiqyajid/react-spotlight/styles.css";

function App() {
  const featureRef = useRef<HTMLDivElement>(null);

  return (
    <>
      <div ref={featureRef}>Feature area</div>

      <SpotlightStyled
        target={featureRef}
        trigger={<button>Highlight</button>}
      >
        <p>Now you see me.</p>
      </SpotlightStyled>
    </>
  );
}

{/* Escape and overlay click disabled — only explicit action closes */}
<SpotlightStyled
  target={ref}
  open={open}
  onOpenChange={setOpen}
  closeOnEscape={false}
  closeOnOverlayClick={false}
>
  <div>
    <p>You must click the button to continue.</p>
    <button onClick={() => setOpen(false)}>Next</button>
  </div>
</SpotlightStyled>

import { useSpotlight } from "@mshafiqyajid/react-spotlight";
import { createPortal } from "react-dom";
import { useRef } from "react";

function MySpotlight() {
  const targetRef = useRef<HTMLButtonElement>(null);
  const { isOpen, open, close, targetRect, overlayProps, spotlightProps, padding, radius } =
    useSpotlight({ target: targetRef, placement: "bottom" });

  return (
    <>
      <button ref={targetRef} onClick={open}>Highlight me</button>

      {isOpen && createPortal(
        <div {...overlayProps}>
          {targetRect && (
            <svg style={{ position: "fixed", inset: 0, width: "100%", height: "100%", pointerEvents: "none" }}>
              <defs>
                <mask id="my-mask">
                  <rect width="100%" height="100%" fill="white" />
                  <rect
                    x={targetRect.x - padding}  y={targetRect.y - padding}
                    width={targetRect.width + padding * 2}
                    height={targetRect.height + padding * 2}
                    rx={radius}
                    fill="black"
                  />
                </mask>
              </defs>
              <rect width="100%" height="100%" fill="rgba(0,0,0,0.6)" mask="url(#my-mask)" />
            </svg>
          )}
          <div {...spotlightProps}>
            <p>Custom content</p>
            <button onClick={close}>Close</button>
          </div>
        </div>,
        document.body
      )}
    </>
  );
}

interface SpotlightStep {
  /** Ref or CSS selector of the element to highlight */
  target: React.RefObject<Element | null> | string;
  /** Padding around the target in px — overrides root padding */
  padding?: number;
  /** Cutout border-radius in px — overrides root radius */
  radius?: number;
  /** Content panel placement — overrides root placement */
  placement?: SpotlightPlacement;
  /** Content rendered in the panel for this step */
  content?: React.ReactNode;
}