Cursor Spotlight for React

Component

"use client";

import { useState } from "react";
import { cn } from "@/lib/utils";

interface CursorSpotlightProps {
  children?: React.ReactNode;
  className?: string;
  spotlightSize?: number;
  spotlightOpacity?: number;
  baseColor?: string;
  falloff?: string;
  childrenClassName?: string;
}

export function CursorSpotlight({
  children,
  className,
  spotlightSize = 100,
  spotlightOpacity = 0.25,
  baseColor = "rgb(2 6 23)",
  falloff = "60%",
  childrenClassName,
}: CursorSpotlightProps) {
  const [pos, setPos] = useState({ x: 50, y: 50 });
  const [hovering, setHovering] = useState(false);

  return (
    <div
      role="img"
      aria-hidden={true}
      className={cn("relative overflow-hidden", className)}
      onMouseMove={(e) => {
        const rect =
          e.currentTarget.getBoundingClientRect();
        setPos({
          x: ((e.clientX - rect.left) / rect.width) * 100,
          y: ((e.clientY - rect.top) / rect.height) * 100,
        });
        setHovering(true);
      }}
      onMouseLeave={() => setHovering(false)}
    >
      <div
        className="absolute inset-0"
        style={{ backgroundColor: baseColor }}
      />
      <div
        className="pointer-events-none absolute inset-0 transition-opacity duration-150"
        style={{
          background: `radial-gradient(circle ${spotlightSize}px at ${pos.x}% ${pos.y}%, rgba(255,255,255,${spotlightOpacity}) 0%, transparent ${falloff})`,
          opacity: hovering ? 1 : 0,
        }}
      />
      {children && (
        <div className={cn("relative", childrenClassName)}>
          {children}
        </div>
      )}
    </div>
  );
}

Installation

"use client";

import { useState } from "react";
import { cn } from "@/lib/utils";

interface CursorSpotlightProps {
  children?: React.ReactNode;
  className?: string;
  spotlightSize?: number;
  spotlightOpacity?: number;
  baseColor?: string;
  falloff?: string;
  childrenClassName?: string;
}

export function CursorSpotlight({
  children,
  className,
  spotlightSize = 100,
  spotlightOpacity = 0.25,
  baseColor = "rgb(2 6 23)",
  falloff = "60%",
  childrenClassName,
}: CursorSpotlightProps) {
  const [pos, setPos] = useState({ x: 50, y: 50 });
  const [hovering, setHovering] = useState(false);

  return (
    <div
      role="img"
      aria-hidden={true}
      className={cn("relative overflow-hidden", className)}
      onMouseMove={(e) => {
        const rect =
          e.currentTarget.getBoundingClientRect();
        setPos({
          x: ((e.clientX - rect.left) / rect.width) * 100,
          y: ((e.clientY - rect.top) / rect.height) * 100,
        });
        setHovering(true);
      }}
      onMouseLeave={() => setHovering(false)}
    >
      <div
        className="absolute inset-0"
        style={{ backgroundColor: baseColor }}
      />
      <div
        className="pointer-events-none absolute inset-0 transition-opacity duration-150"
        style={{
          background: `radial-gradient(circle ${spotlightSize}px at ${pos.x}% ${pos.y}%, rgba(255,255,255,${spotlightOpacity}) 0%, transparent ${falloff})`,
          opacity: hovering ? 1 : 0,
        }}
      />
      {children && (
        <div className={cn("relative", childrenClassName)}>
          {children}
        </div>
      )}
    </div>
  );
}

import { CursorSpotlight } from "@/components/cursor-spotlight";

<CursorSpotlight>Content</CursorSpotlight>;

Usage

import { CursorSpotlight } from "@/components/cursor-spotlight";

<CursorSpotlight>Content</CursorSpotlight>;

Props

All props are optional unless marked required. Use these to customize every aspect of the component.

Accessibility

• Decorative visual effect with no interactive controls or focusable elements; the wrapper is marked role img and aria-hidden true so the spotlight layer is skipped by assistive technology.
• The effect is driven entirely by mouse position with no keyboard handler, so keyboard-only users see only the static dimmed background and never trigger the spotlight.
• Any meaningful content passed as children is rendered in a normal relative div and stays in the accessibility tree, but authors should ensure that content has sufficient contrast against the dimmed base color.
• The component does not check prefers-reduced-motion, so it should be guarded for users who prefer reduced motion by disabling the opacity fade and cursor tracking when that media query matches.

Performance

• The visible reveal animates only opacity via a 150ms transition, which is a cheap GPU-compositable property that does not trigger layout.
• Every mousemove rebuilds the radial-gradient background string in an inline style, forcing a continuous paint of the full-size layer that is not GPU-compositable and is the main cost of the effect.
• Cursor tracking updates React state on each mousemove, causing a re-render per event rather than batching through requestAnimationFrame, so rapid movement over a large container can be paint and render heavy.
• It uses React synthetic onMouseMove and onMouseLeave handlers with no manually attached listeners or timers, so there is nothing to clean up and no leak risk.
• There is no IntersectionObserver, will-change, or visibility gating, so the spotlight layer keeps repainting whenever the pointer is inside the container regardless of whether it is in view.

Related reading

• Moving Things Without Moving Them — Tracking the cursor with transforms instead of layout
• Offloading Motion to the GPU — Why the spotlight uses GPU-friendly properties