{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"bg-stars","type":"registry:ui","title":"StarsBackground","description":"Three-layer starfield background that scrolls continuously while parallax-shifting in response to cursor movement via spring physics, with stars rendered as box-shadow dots across near, mid, and far depth layers","author":"fancy-ui <https://fancy-ui.rama.app>","categories":["backgrounds"],"registryDependencies":["https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/bg-stars/StarsBackground.tsx","content":"\"use client\";\n\nimport {\n\tuseEffect,\n\tuseMemo,\n\tuseRef,\n\ttype CSSProperties,\n\ttype MouseEvent,\n\ttype ReactNode,\n} from \"react\";\nimport { cn } from \"../../utils\";\nimport \"./bg-stars.css\";\n\nexport interface StarsBackgroundProps {\n\t/**\n\t * Parallax factor for mouse movement (default: 0.05)\n\t */\n\tfactor?: number;\n\t/**\n\t * Base animation speed in seconds (default: 50)\n\t */\n\tspeed?: number;\n\t/**\n\t * Spring stiffness for parallax (default: 50)\n\t */\n\tstiffness?: number;\n\t/**\n\t * Spring damping for parallax (default: 20)\n\t */\n\tdamping?: number;\n\t/**\n\t * Color of the stars (default: #fff)\n\t */\n\tstarColor?: string;\n\t/**\n\t * Seed for the star layout. The same seed always produces the same sky.\n\t * The Svelte side scatters stars with `Math.random()` in a client-only\n\t * effect; a render-path `Math.random()` would differ between a server\n\t * render and its hydration, so the port derives the layout from a\n\t * deterministic PRNG instead (default: 1).\n\t */\n\tseed?: number;\n\t/**\n\t * Additional CSS classes\n\t */\n\tclassName?: string;\n\t/**\n\t * Child content to render over the stars\n\t */\n\tchildren?: ReactNode;\n}\n\n/**\n * mulberry32 — a tiny deterministic PRNG. `Math.random()` cannot be used\n * here: the star field renders in the render path, so its output must be\n * identical between a server render and its hydration. A seed keeps both\n * renders identical AND keeps the sky stable across unrelated re-renders.\n */\nfunction mulberry32(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn () => {\n\t\tstate = (state + 0x6d2b79f5) | 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), 1 | state);\n\t\tt = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\nfunction generateStars(count: number, color: string, random: () => number): string {\n\tconst shadows: string[] = [];\n\tfor (let i = 0; i < count; i++) {\n\t\tconst x = Math.floor(random() * 4000) - 2000;\n\t\tconst y = Math.floor(random() * 4000) - 2000;\n\t\tshadows.push(`${x}px ${y}px ${color}`);\n\t}\n\treturn shadows.join(\", \");\n}\n\nexport function StarsBackground({\n\tfactor = 0.05,\n\tspeed = 50,\n\tstiffness = 50,\n\tdamping = 20,\n\tstarColor = \"#fff\",\n\tseed = 1,\n\tclassName,\n\tchildren,\n}: StarsBackgroundProps) {\n\t// Star box-shadows. The Svelte source regenerates them in an effect keyed\n\t// on `starColor`; here they are derived on the same dependency (plus the\n\t// seed that replaces `Math.random()`), so an unrelated re-render never\n\t// reshuffles the sky.\n\tconst [boxShadow1, boxShadow2, boxShadow3] = useMemo(() => {\n\t\tconst random = mulberry32(seed);\n\t\treturn [\n\t\t\tgenerateStars(1000, starColor, random),\n\t\t\tgenerateStars(400, starColor, random),\n\t\t\tgenerateStars(200, starColor, random),\n\t\t];\n\t}, [starColor, seed]);\n\n\t// Spring animation state. Per-frame values never round-trip through React\n\t// state — the loop writes `transform` straight onto the parallax element,\n\t// exactly where the Svelte template binds `style:transform`.\n\tconst parallaxEl = useRef<HTMLDivElement | null>(null);\n\tconst target = useRef({ x: 0, y: 0 });\n\tconst velocity = useRef({ x: 0, y: 0 });\n\tconst spring = useRef({ x: 0, y: 0 });\n\t// Wakes the spring loop back up. The loop parks itself once the spring has\n\t// settled, so a new pointer target has to restart it. Assigned by the\n\t// effect below; a no-op while the component is unmounted.\n\tconst wakeSpring = useRef(() => {});\n\n\tfunction handleMouseMove(e: MouseEvent<HTMLDivElement>) {\n\t\tconst centerX = window.innerWidth / 2;\n\t\tconst centerY = window.innerHeight / 2;\n\t\ttarget.current.x = -(e.clientX - centerX) * factor;\n\t\ttarget.current.y = -(e.clientY - centerY) * factor;\n\t\twakeSpring.current();\n\t}\n\n\t// The spring loop. Spring position and velocity live in refs, so a restart\n\t// on a stiffness/damping change (its only actual inputs) resumes from the\n\t// in-flight position instead of snapping back to rest.\n\tuseEffect(() => {\n\t\t// Sub-pixel: under this the spring neither moves the layer nor sits\n\t\t// visibly away from its target, so the loop parks instead of writing\n\t\t// the same transform every frame for the page's whole life.\n\t\tconst REST_EPSILON = 0.01;\n\t\tlet animationFrame = 0;\n\n\t\tfunction updateSpring() {\n\t\t\tanimationFrame = 0;\n\n\t\t\t// Simple spring physics\n\t\t\tconst forceX = (target.current.x - spring.current.x) * (stiffness / 1000);\n\t\t\tconst forceY = (target.current.y - spring.current.y) * (stiffness / 1000);\n\n\t\t\tvelocity.current.x = velocity.current.x * (1 - damping / 100) + forceX;\n\t\t\tvelocity.current.y = velocity.current.y * (1 - damping / 100) + forceY;\n\n\t\t\tspring.current.x += velocity.current.x;\n\t\t\tspring.current.y += velocity.current.y;\n\n\t\t\tconst atRest =\n\t\t\t\tMath.abs(velocity.current.x) < REST_EPSILON &&\n\t\t\t\tMath.abs(velocity.current.y) < REST_EPSILON &&\n\t\t\t\tMath.abs(target.current.x - spring.current.x) < REST_EPSILON &&\n\t\t\t\tMath.abs(target.current.y - spring.current.y) < REST_EPSILON;\n\n\t\t\tif (atRest) {\n\t\t\t\t// Land exactly on the target so the parked transform matches\n\t\t\t\t// the one the loop would have converged to.\n\t\t\t\tvelocity.current.x = 0;\n\t\t\t\tvelocity.current.y = 0;\n\t\t\t\tspring.current.x = target.current.x;\n\t\t\t\tspring.current.y = target.current.y;\n\t\t\t}\n\n\t\t\tif (parallaxEl.current) {\n\t\t\t\tparallaxEl.current.style.transform = `translate(${spring.current.x}px, ${spring.current.y}px)`;\n\t\t\t}\n\n\t\t\tif (!atRest) {\n\t\t\t\tanimationFrame = requestAnimationFrame(updateSpring);\n\t\t\t}\n\t\t}\n\n\t\tfunction start() {\n\t\t\t// Idempotent: a second wake while a frame is already queued, or\n\t\t\t// while the page is in a background tab, changes nothing.\n\t\t\tif (animationFrame !== 0 || document.hidden) return;\n\t\t\tanimationFrame = requestAnimationFrame(updateSpring);\n\t\t}\n\n\t\tfunction stop() {\n\t\t\tif (animationFrame !== 0) {\n\t\t\t\tcancelAnimationFrame(animationFrame);\n\t\t\t\tanimationFrame = 0;\n\t\t\t}\n\t\t}\n\n\t\tfunction handleVisibilityChange() {\n\t\t\tif (document.hidden) {\n\t\t\t\tstop();\n\t\t\t} else {\n\t\t\t\tstart();\n\t\t\t}\n\t\t}\n\n\t\twakeSpring.current = start;\n\t\tstart();\n\t\tdocument.addEventListener(\"visibilitychange\", handleVisibilityChange);\n\n\t\treturn () => {\n\t\t\twakeSpring.current = () => {};\n\t\t\tstop();\n\t\t\tdocument.removeEventListener(\"visibilitychange\", handleVisibilityChange);\n\t\t};\n\t}, [stiffness, damping]);\n\n\t// Derived CSS custom properties for animation durations\n\tconst layer1Duration = `${speed}s`;\n\tconst layer2Duration = `${speed * 2}s`;\n\tconst layer3Duration = `${speed * 3}s`;\n\n\treturn (\n\t\t<div\n\t\t\tclassName={cn(\n\t\t\t\t// `fancy-bg-stars` is a port-added anchor for the colocated CSS\n\t\t\t\t// (PORTING.md, styling rule 2). Not the bare slug: tailwind-merge\n\t\t\t\t// classifies a `bg-*` token as a background class and would drop\n\t\t\t\t// it against a consumer-supplied `bg-*` override.\n\t\t\t\t\"fancy-bg-stars relative size-full overflow-hidden bg-[radial-gradient(ellipse_at_bottom,_#262626_0%,_#000_100%)]\",\n\t\t\t\tclassName\n\t\t\t)}\n\t\t\tonMouseMove={handleMouseMove}\n\t\t>\n\t\t\t<div\n\t\t\t\tref={parallaxEl}\n\t\t\t\tclassName=\"stars-parallax\"\n\t\t\t\tstyle={{ transform: \"translate(0px, 0px)\" }}\n\t\t\t>\n\t\t\t\t{/* Star Layer 1 (smallest, fastest) */}\n\t\t\t\t<div className=\"star-layer\" style={{ \"--duration\": layer1Duration } as CSSProperties}>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"star-field\"\n\t\t\t\t\t\tstyle={{ width: \"1px\", height: \"1px\", boxShadow: boxShadow1 }}\n\t\t\t\t\t></div>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"star-field top-[2000px]\"\n\t\t\t\t\t\tstyle={{ width: \"1px\", height: \"1px\", boxShadow: boxShadow1 }}\n\t\t\t\t\t></div>\n\t\t\t\t</div>\n\n\t\t\t\t{/* Star Layer 2 (medium) */}\n\t\t\t\t<div className=\"star-layer\" style={{ \"--duration\": layer2Duration } as CSSProperties}>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"star-field\"\n\t\t\t\t\t\tstyle={{ width: \"2px\", height: \"2px\", boxShadow: boxShadow2 }}\n\t\t\t\t\t></div>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"star-field top-[2000px]\"\n\t\t\t\t\t\tstyle={{ width: \"2px\", height: \"2px\", boxShadow: boxShadow2 }}\n\t\t\t\t\t></div>\n\t\t\t\t</div>\n\n\t\t\t\t{/* Star Layer 3 (largest, slowest) */}\n\t\t\t\t<div className=\"star-layer\" style={{ \"--duration\": layer3Duration } as CSSProperties}>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"star-field\"\n\t\t\t\t\t\tstyle={{ width: \"3px\", height: \"3px\", boxShadow: boxShadow3 }}\n\t\t\t\t\t></div>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"star-field top-[2000px]\"\n\t\t\t\t\t\tstyle={{ width: \"3px\", height: \"3px\", boxShadow: boxShadow3 }}\n\t\t\t\t\t></div>\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/* Child content over the stars */}\n\t\t\t{children}\n\t\t</div>\n\t);\n}\n","type":"registry:ui","target":"@ui/fancy/components/bg-stars/StarsBackground.tsx"},{"path":"react/src/components/bg-stars/bg-stars.css","content":"/*\n * `.fancy-bg-stars` is a PORT-ADDED anchor (PORTING.md, styling rule 2). The\n * Svelte source has no root class: its compiler scoped `.stars-parallax` /\n * `.star-layer` / `.star-field`, which would leak into any consumer element\n * with those names once the rules ship as plain global CSS. The anchor is the\n * first token of the root `cn()` call in StarsBackground.tsx. (`bg-stars`\n * itself is avoided because tailwind-merge treats `bg-*` as a background\n * utility and would drop it.)\n */\n.fancy-bg-stars .stars-parallax {\n\twill-change: transform;\n}\n\n.fancy-bg-stars .star-layer {\n\tposition: absolute;\n\ttop: 0;\n\tleft: 0;\n\twidth: 100%;\n\theight: 2000px;\n\tanimation: scroll-stars var(--duration, 50s) linear infinite;\n}\n\n.fancy-bg-stars .star-field {\n\tposition: absolute;\n\tbackground: transparent;\n\tborder-radius: 50%;\n}\n\n@keyframes scroll-stars {\n\tfrom {\n\t\ttransform: translateY(0);\n\t}\n\tto {\n\t\ttransform: translateY(-2000px);\n\t}\n}\n","type":"registry:ui","target":"@ui/fancy/components/bg-stars/bg-stars.css"},{"path":"react/src/components/bg-stars/index.ts","content":"\"use client\";\n\nexport { StarsBackground } from \"./StarsBackground\";\nexport type { StarsBackgroundProps } from \"./StarsBackground\";\n","type":"registry:ui","target":"@ui/fancy/components/bg-stars/index.ts"}],"meta":{"license":"MIT","package":"fancy-ui-react","version":"0.7.0","source":"https://fancy-ui.rama.app/docs/components/bg-stars?framework=react"}}