ComponentsStarfieldBackground
StarfieldBackground
Add a drifting star background with optional pointer movement.
On this page
Use this component from the local workspace package. Follow the setup guide first. A public npm package and registry are not available yet.
View registry filesImport the component into your page or component file.
import { StarfieldBackground } from "@dethink/components";Try the examples, then open the code to use them in your app. The background fills its container; these previews bound it with a height utility. Move your cursor over the first example to feel the parallax.
Hero composition
The default composition: hero copy and actions render in the content slot above the animated layer, which never intercepts pointer events.
Built for what ships next
Three star layers drift at different speeds and lean gently toward your cursor — an expansive surface with calm parallax depth.
Show sourceexamples/starfield-background/basic.tsx
"use client";
import { Badge, Button, StarfieldBackground } from "@dethink/components";
export function StarfieldBackgroundBasic() {
return (
<StarfieldBackground
className="border-border h-[24rem] rounded-lg border"
tone="foreground"
>
<div className="flex h-[24rem] flex-col items-center justify-center gap-4 px-6 text-center">
<Badge tone="primary" variant="soft">
Launch window open
</Badge>
<h2 className="text-foreground max-w-xl text-3xl font-semibold tracking-tight">
Built for what ships next
</h2>
<p className="text-muted-foreground max-w-md text-sm leading-6">
Three star layers drift at different speeds and lean gently toward
your cursor — an expansive surface with calm parallax depth.
</p>
<div className="flex gap-3">
<Button>Reserve access</Button>
<Button variant="outline">See the roadmap</Button>
</div>
</div>
</StarfieldBackground>
);
}Density, interactivity, and speed
Every visual axis is a literal token-backed variant; interactive={false} keeps the drift but drops the pointer response.
Show sourceexamples/starfield-background/variants.tsx
"use client";
import { StarfieldBackground } from "@dethink/components";
export function StarfieldBackgroundVariants() {
return (
<div className="grid gap-4 sm:grid-cols-3">
<StarfieldBackground
className="border-border h-48 rounded-lg border"
density="dense"
intensity="bold"
seed={3}
speed="fast"
tone="primary"
>
<div className="flex h-48 items-end p-4">
<span className="text-muted-foreground text-xs font-medium">
tone="primary" · dense · bold · fast
</span>
</div>
</StarfieldBackground>
<StarfieldBackground
className="border-border h-48 rounded-lg border"
interactive={false}
seed={5}
tone="muted"
>
<div className="flex h-48 items-end p-4">
<span className="text-muted-foreground text-xs font-medium">
interactive={"{false}"} · drift only
</span>
</div>
</StarfieldBackground>
<StarfieldBackground
className="border-border h-48 rounded-lg border"
density="sparse"
seed={9}
speed="slow"
tone="foreground"
>
<div className="flex h-48 items-end p-4">
<span className="text-muted-foreground text-xs font-medium">
tone="foreground" · sparse · slow
</span>
</div>
</StarfieldBackground>
</div>
);
}Static frame
animate={false} — and any user with a reduced-motion preference — gets this composition: no loops or pointer handlers mounted, still designed.
Designed at rest
animate={false} renders the same frame reduced-motion users see: every star still, twinkles at mid brightness, no drift and no pointer response.
Show sourceexamples/starfield-background/static.tsx
"use client";
import { StarfieldBackground } from "@dethink/components";
export function StarfieldBackgroundStatic() {
return (
<StarfieldBackground
animate={false}
className="border-border h-56 rounded-lg border"
tone="foreground"
>
<div className="flex h-56 flex-col items-center justify-center gap-2 px-6 text-center">
<h3 className="text-foreground text-xl font-semibold">
Designed at rest
</h3>
<p className="text-muted-foreground max-w-sm text-sm leading-6">
animate={"{false}"} renders the same frame reduced-motion users see:
every star still, twinkles at mid brightness, no drift and no pointer
response.
</p>
</div>
</StarfieldBackground>
);
}StarfieldBackground accepts div props plus the shared background contract — animate, density, intensity, speed, tone, seed — and its own interactive axis.
| Prop | What it does | Default |
|---|---|---|
animateboolean | Set to false to force the static composition regardless of OS motion preference: every star still, twinkles at mid brightness, and no drift or pointer parallax mounted. | true |
interactiveboolean | Enables pointer parallax: layers ease toward the cursor via spring-smoothed motion values with depth increasing from the far to the near layer (3/6/10px). Automatically disabled under reduced motion. Reflected as data-interactive. | true |
density"sparse" | "normal" | "dense" | Star count per layer (50/82/124 total stars plus twinkles). The far layer always carries the most, smallest stars. | "normal" |
intensity"faint" | "subtle" | "bold" | Opacity tier for the stars. Keep faint or subtle under body copy; bold suits dark, short hero statements. | "subtle" |
speed"slow" | "normal" | "fast" | Scales the per-layer drift loop durations (base 120/90/60s, mirrored). The far layer always drifts slowest, which creates the parallax. Loops pause automatically while the background is offscreen. | "normal" |
tone"foreground" | "muted" | "primary" | Semantic token driving the star color via currentColor, so light and dark mode adapt automatically. | "muted" |
seednumber | Drives every star and twinkle position deterministically, so markup is SSR-stable across server and client renders; change it for a different sky. | 1 |
childrenReactNode | Hero content rendered in the content slot above the aria-hidden decorative layer. The layer is pointer-events-none, so children stay fully interactive. | Not set |
getStarfieldBackgroundMotionConfig / getStarfieldBackgroundGeometry / *ClassNames helpers(speed, reducedMotion) => config, (seed, density) => layers, ({ className }) => string | Open-code escape hatches: read the drift durations and parallax depths, reuse the seeded star geometry, or apply the root, layer, and content class recipes to custom elements. | Not set |