# Searchlight hero

> A hero whose picture sits in the dark: a lamp in it casts a cone of light that sweeps the scene, follows the pointer, finds things and lights the headline as it passes.

A hero with a big illustration usually just shows it, or plays a heavy video of it moving. This one keeps the picture in the dark and gives it a light. The scene is graded into two deep tones of your primary colour, so the headline reads on it and the block takes on your brand; a lamp in the picture flickers on and casts a cone with a crisp edge, inside which the painting is in full, warm colour, with marine snow sinking through the beam. Left alone, the beam scans slowly across the scene. Move the pointer and it swings to follow on a spring, or drag sideways on a phone. Spots you mark in the picture get a ring and a label when the light finds them, and the words of the headline light up one by one as the beam crosses them. It is one picture and one small WebGL shader: no video, no animation library, nothing that runs off screen.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/searchlight-hero.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/searchlight-hero
- Registry item (source): https://hairlineui.com/r/searchlight-hero.json

## Usage

```tsx
import { SearchlightHero } from "@/components/searchlight-hero";

<SearchlightHero
  title="Find what's broken before your customers do."
  description="Fathom crawls every page each night and lights up what's broken."
  primary={{ label: "Run a free audit", href: "/signup" }}
/>
```

## With your own picture

Use any illustration or photo with a light source in it (a lamp, a window, a torch); give the lamp’s position as fractions of the picture, and the spots you want found.

```tsx
import { SearchlightHero } from "@/components/searchlight-hero";

export default function Home() {
  return (
    <main className="mx-auto max-w-[1240px] p-4">
      <SearchlightHero
        eyebrow="Lantern · security scans"
        title="See every open door before someone else does."
        description="Lantern scans your cloud each hour and shows the exposed buckets, stale keys and open ports, with the fix for each."
        primary={{ label: "Start a scan", href: "/signup" }}
        secondary={{ label: "See a sample report", href: "/report" }}
        image="/hero/lighthouse.webp"
        alt="A lighthouse over a harbour at night"
        lamp={{ x: 0.78, y: 0.22 }}
        rest={{ x: 0.35, y: 0.7 }}
        finds={[
          { x: 0.3, y: 0.62, label: "Public bucket · invoices-2026" },
          { x: 0.52, y: 0.8, label: "Stale key · unused 214 days" },
        ]}
      />
    </main>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | – | The headline; its words light as the beam crosses them. |
| `description` | `string` | – | One paragraph under the title. |
| `eyebrow` | `string` | – | A short line above the title. |
| `primary` | `{ label: string; href: string }` | – | The main action, a lit plate. |
| `secondary` | `{ label: string; href: string }` | – | A second action with a hairline ring. |
| `image` | `string` | `the deep-sea painting` | Your picture: a URL (same origin, or served with CORS) or a data URI. |
| `alt` | `string` | – | What the picture shows, for screen readers. |
| `lamp` | `{ x: number; y: number }` | `{ x: 0.709, y: 0.173 }` | Where the light comes from, as fractions of the picture. |
| `lampSize` | `number` | `0.011` | The lamp's lens radius as a share of the picture's width. |
| `rest` | `{ x: number; y: number }` | `{ x: 0.4, y: 0.76 }` | Where the beam rests and centres its sweep. |
| `focus` | `{ x: number; y: number }` | `{ x: 0.62, y: 0.55 }` | What stays in view when the picture is cropped to the box (on phones it is much narrower than the picture). |
| `finds` | `{ x: number; y: number; label: string }[]` | `[]` | Spots the beam can find; outside the crop they are hidden. |
| `as` | `"h1" \| "h2"` | `"h1"` | The title's element. |

## States

- **on**: When the hero first comes into view the lamp flickers twice and comes on over 0.9s; the cone opens out of the dark picture.
- **sweep**: Left alone, the beam scans to and fro across the picture, a 12s pass on a soft spring, centred on rest.
- **aim**: The pointer takes the beam, which follows it on a quicker spring; on a phone a sideways drag aims it and a vertical swipe still scrolls. 2.5s after the pointer stops it goes back to sweeping from where it is.
- **found**: A spot in finds inside the beam gets a 1px ring and its label rises out of a 3px blur above it (300ms); it stays 1.4s after the light moves on.
- **reads**: Words of the title sit at 66% until the beam crosses them, then light to full in 300ms.
- **still**: With reduced motion the lamp is simply on, the beam rests on rest, nothing sinks and the title is at full strength.

## What it handles

Illustrated heroes either sit still or ship a video loop that can never be your own picture. This block brings any image to life in code and keeps it legible.

- **Any picture**: Pass image and the point the lamp is at; the light, the grade and the crop all follow it.
- **Your brand in the dark**: Outside the beam the picture is graded into two tones of --primary, read from the theme and updated when it changes.
- **Legible type**: The night grade keeps the headline and buttons readable on any part of the picture.
- **Things it finds**: finds marks spots in the picture; each gets a ring and its label while the beam is on it.
- **Light and fast**: One draw call a frame, only while on screen, with the canvas capped at 1.5× pixel density; the picture shows dark on first paint.
- **Falls back**: Without WebGL a still wedge of light is cut out of the picture; with reduced motion the beam rests in one place.

## Replaces

a hero video, a spotlight cursor effect, a parallax hero, an image overlay gradient, a scroll animation library

## Where it fits

- **Product launches**: The first screen of a launch page, where one picture has to stop the scroll.
- **Search and discovery**: Products that find things: audits, monitoring, research, security scans.
- **Agency and studio sites**: A showcase hero that turns any commissioned illustration into a scene.
- **Campaign pages**: A seasonal or story page that wants motion without shipping a video.

## Notes

- The picture is one element with role="img" and your alt; the title is read once as plain text (its lit words are a copy hidden from screen readers); the found labels are decoration. Both actions are links.
- The light is one fragment shader over the picture (searchlight-gl.ts): the night grade, the cone with its 1px rim, the haze and two layers of marine snow are uniforms, so a frame is one draw call. It runs only while the hero is on screen and the tab is visible, at no more than 1.5× pixel density.
- The beam is an angle on a critically damped spring written straight to the shader; no React state changes while it moves, and words and labels change class only when the light reaches or leaves them.
- On first paint, and until the picture has loaded, the same picture shows darkened by a CSS filter, cropped exactly as the canvas will be. Without WebGL it stays, with a still wedge of light cut out of a full-colour copy.
- With reduced motion the lamp doesn’t flicker, the beam rests on rest, the snow doesn’t move and the pointer doesn’t aim it.
- The default deep-sea painting ships inside searchlight-art.ts as one WebP (322KB) so the install is complete; pass image to use yours and the default is never loaded.

License: MIT (https://hairlineui.com/license#components)
