Gravity Stars

Interactive canvas background with gravity-driven star particles, mouse attraction/repulsion, click-to-spawn, and star collisions.

Installation

File Structure

gravity-stars.tsx

Usage

import { GravityStarsBackground } from "@/components/unlumen-ui/gravity-stars";
<GravityStarsBackground className="absolute inset-0" />

Interactions

  • Hover — stars are attracted or repelled based on mouseGravity
  • Click — spawns a burst of new stars at the cursor position
  • Star collisions — stars can bounce off or merge with each other when starsInteraction is enabled

Examples

Repel on hover

<GravityStarsBackground mouseGravity="repel" gravityStrength={120} />

Star collisions with merge

<GravityStarsBackground starsInteraction starsInteractionType="merge" />

Custom colors and density

<GravityStarsBackground
  starsCount={150}
  starsColor="#60a5fa"
  starsSize={3}
  glowIntensity={25}
/>

API Reference

GravityStarsBackground

PropTypeDefault
starsCount?
number
75
starsSize?
number
2
starsOpacity?
number
0.75
starsColor?
string
"#ffcad4"
glowIntensity?
number
15
glowAnimation?
'instant' | 'ease' | 'spring'
"ease"
movementSpeed?
number
0.3
mouseInfluence?
number
100
mouseGravity?
'attract' | 'repel'
"attract"
gravityStrength?
number
75
starsInteraction?
boolean
false
starsInteractionType?
'bounce' | 'merge'
"bounce"
...props?
React.ComponentProps<"div">
-

Notes

  • The canvas uses devicePixelRatio (capped at 2) for crisp rendering on retina displays. The DPR is applied to canvas dimensions and draw calls automatically.
  • An IntersectionObserver pauses the animation loop when the component is off-screen — no wasted frames.
  • A ResizeObserver on the container keeps the canvas sized correctly inside flex/grid layouts. No need to handle resize yourself.
  • Clicking anywhere spawns 4 new stars at the cursor position. Stars are capped at 80 total — older stars are removed first when the cap is exceeded.
  • Star collisions are O(n²) — with starsInteraction enabled and high starsCount, performance can drop. Keep starsCount under ~100 when collisions are on.
  • The glowAnimation prop controls how the glow responds to mouse proximity: "instant" snaps immediately, "ease" interpolates smoothly (15% per frame), "spring" uses a damped spring with velocity tracking.
  • Stars wrap around edges (toroidal space) — a star leaving the right side reappears on the left.
  • All physics run in logical (CSS) pixel space, not canvas pixels. Mouse coordinates are converted from getBoundingClientRect offsets.

Credits

  • Thanks to Animate UI for the original inspiration and base component idea.
  • Credits to Brett Jackson for the initial Framer component concept.