Gravity Stars

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

Installation

Pro components require registry authentication. Add your Unlumen UI Pro key as UNLUMEN_LICENSE_KEY in your .env.local file and follow the setup guide.

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

starsCount?
number
75

Initial number of stars.

starsSize?
number
2

Maximum radius of each star in pixels.

starsOpacity?
number
0.75

Base opacity of the stars.

starsColor?
string
"#ffcad4"

Color of the stars (any CSS color).

glowIntensity?
number
15

Shadow blur intensity applied to each star.

glowAnimation?
'instant' | 'ease' | 'spring'
"ease"

How the glow responds to mouse proximity — instant snap, smooth ease, or spring physics.

movementSpeed?
number
0.3

Base movement speed of the stars.

mouseInfluence?
number
100

Radius in pixels around the cursor that affects stars.

mouseGravity?
'attract' | 'repel'
"attract"

Whether the cursor attracts or repels stars.

gravityStrength?
number
75

Strength of the gravitational force applied to stars.

starsInteraction?
boolean
false

Whether stars interact with each other on collision.

starsInteractionType?
'bounce' | 'merge'
"bounce"

Collision behavior between stars — rigid bounce or soft merge with glow.

...props?
React.ComponentProps<"div">
—

All other props are forwarded to the root 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.

Keep in mind

Most components on this site are inspired by or recreated from existing work across the web. I'm not here to take credit; just to learn, experiment, and sometimes push things a bit further. If something looks familiar and I forgot to mention you, reach out and I'll fix that right away.