Skip to content
VenusUI
Get started

Spotlight Card

A card with a soft light that follows the pointer.

Preview

Installation

npx shadcn@latest add @venusui/spotlight-card

Run this in a project set up with shadcn. If you haven’t set it up yet, run npx shadcn@latest init first.

Files added to your project

Paths use the default shadcn aliases. The CLI follows the aliases in your components.json.

  • @/hooks/use-pointer-position.tsfrom use-pointer-position
  • @/lib/compose-refs.tsfrom compose-refs
  • @/components/ui/spotlight-card.tsx

Usage

The code behind the preview above.

spotlight-card-demo.tsx

import { SpotlightCard } from "@/components/ui/spotlight-card"

export default function SpotlightCardDemo() {
  return (
    <SpotlightCard className="w-full max-w-sm p-6">
      <p className="text-sm font-medium text-muted-foreground">Usage this month</p>
      <p className="mt-2 text-3xl font-semibold tracking-tight">12,480</p>
      <p className="mt-1 text-sm text-muted-foreground">Move your pointer across the card.</p>
    </SpotlightCard>
  )
}

API reference

PropTypeDefaultDescription
spotlightColorstringforeground at 10%Color of the light. Any CSS color, e.g. rgb(59 130 246 / 0.25).
radiusnumber320Radius of the light, in pixels.

All <div> props, including className, style, children and ref.

Requirements

  • React 19. The card receives ref as a prop and uses a ref cleanup function.
  • Tailwind CSS v4 and a cn helper at @/lib/utils, which npx shadcn@latest init creates.

Customization

  • Style the card with className. Classes are merged with cn, so className="rounded-2xl p-8" replaces the default radius and padding.
  • The light is drawn from CSS variables on the card: --spotlight-color and --spotlight-radius (set from the props), and --pointer-x / --pointer-y (written by usePointerPosition).
  • usePointerPosition works on its own: attach the ref it returns to any element to get --pointer-x, --pointer-y and --pointer-active for your own effects.

Accessibility

  • The light is decorative: it is aria-hidden and hidden when the user prefers reduced motion.
  • The card adds no role. Put headings, text and controls inside as you normally would.

Troubleshooting

The light doesn’t appear.
It only shows while a pointer is over the card, and is hidden when reduced motion is on. On light backgrounds, pass a stronger spotlightColor.
TypeScript error on ref.
The component targets React 19, where ref is a regular prop. Upgrade React, or remove the ref handling.
Unknown registry "@venusui"
Your shadcn CLI couldn’t find the namespace in the shadcn registry index. Use the latest CLI (npx shadcn@latest), install by URL, or register it with its address: npx shadcn@latest registry add @venusui=https://venusui.com/r/{name}.json.
No components.json found
Run npx shadcn@latest init in your project first.
Loading preview

Cards whose borders light up near the pointer, as if a light moved across them.

Loading preview

A card that tilts in 3D toward the pointer with spring physics.

Loading preview

A flight boarding pass with a perforated stub and code that flips to the fare and baggage details.