interlace

Stars Background

Three night-sky layers you stack behind hero content: `StarsBackground`, a canvas of density-seeded twinkling stars; `ShootingStars`, one SVG streak at a time; and `Meteors`, CSS-animated tails falling at a fixed 215°.

decorativeclientuiv1.1.0

Preview

Stars Background — live renderaceternity-starsbackground--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL
npx shadcn@latest add https://ds.interlace.tools/r/stars-background.json
With the @interlace alias
npx shadcn@latest add @interlace/stars-background

History

This component is at v1.1.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

@interlace/ui 1.1.02 entries

  • Changedpatch

    Six defects found by upgrading a real consumer, plus five found by reading the components closely enough to document them. **Meteors' glow never painted.** It read var(--color-meteor-glow) while its cssVars declare --meteor-glow; --color-* is the Tailwind @theme namespace and only cssVars.theme populates it, so the whole box-shadow was invalid at computed-value time. **This was broken only for registry consumers** — our own docs site hand-declares the --color- form. **ArticleCard cropped 28% off every cover.** h-44 is 176px; at a ~302px tile that is a 1.72:1 box against a 2.381:1 image. Now aspect-[1000/420] — the ratio the card already declared on its <img>. It also gains a renderImage slot, because every Next.js consumer was re-patching the same line to use next/image and the design system cannot depend on it. **BorderBeam and StarsBackground had no aria-hidden at all** — six purely decorative nodes a screen reader walked. **CloudParticles defaulted bodyColor to currentColor**, painting volumetric clouds in the inherited text colour. **NumberTicker gains notation**, because six-figure metrics overflow a tile at 320px. Also: SheetCompose and DialogCompose each mounted a second backdrop, so a composed dialog dimmed the page twice as much as the hand-composed tree the docs show; Accordion dropped className on the animated Panel; Tooltip accepted delay and discarded it; PopoverAnchor was a second trigger. **useReducedMotion was one frame late.** The canonical useState(false) plus effect returns false on the first render, so every gated component painted one frame of exactly the motion the user turned off. useSyncExternalStore reads during render and closes that on client renders; on hydration the server cannot know the preference, which is what the stylesheet reset is for. Badge drops 'use client' — verified with a real server-component build.

    Components
  • Changedpatch

    The three entry animations in styles/theme.css now run at 200ms with no delay, and the reduced-motion class list in styles/tokens.css covers .animate-pulse. .animate-fade-in-up was 0.5s, .animate-slide-in-left 0.5s behind a 0.3s delay, and .animate-scale-in 0.4s behind a 0.2s delay — up to 800ms before the reader saw anything, against the 200ms entry ceiling MOTION_PHILOSOPHY.md has always set. All three are now 0.2s ease-out both. The delays were the worse half: an entry animation is already laid out at opacity: 0, so a delay is time spent looking at nothing. Separately, .animate-pulse — the animation Skeleton renders on every loading state — was missing from the tokens.css reduced-motion list, along with .animate-meteor and .animate-meteor-effect. The universal clamp in styles/preflight.css was already covering all three, so apps importing styles/index.css were never affected; apps that import tokens.css and theme.css à la carte and skip preflight.css were. All three are now listed. Both are held by packages/ui/__tests__/motion-contract-lock.test.ts, which reads the ceiling out of MOTION_PHILOSOPHY.md rather than repeating it, and fails if any bare animate-* utility in packages/ui/src is missing from the list.

    Components

Import

3 named exports — pull the parts you need.

Public API
import { Meteors, ShootingStars, StarsBackground } from '@/components/ui/aceternity/stars-background';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

StarsBackground                  (canvas — 2D context, resized by a
                                    ResizeObserver, repainted per rAF frame)
  ShootingStars                    (svg > rect + linearGradient#gradient)
  Meteors                          (div > injected <style> + span ×number)

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

StarProps

PropTypeDescription
x*number—
y*number—
radius*number—
opacity*number—
twinkleSpeed*number | null—

StarBackgroundProps

PropTypeDescription
starDensitynumber—
allStarsTwinkleboolean—
twinkleProbabilitynumber—
minTwinkleSpeednumber—
maxTwinkleSpeednumber—
classNamestring—

ShootingStarProps

PropTypeDescription
minSpeednumber—
maxSpeednumber—
minDelaynumber—
maxDelaynumber—
starColorstring—
trailColorstring—
starWidthnumber—
starHeightnumber—
classNamestring—

MeteorsProps

PropTypeDescription
numbernumberNumber of meteors to display
minDurationnumberMinimum animation duration in seconds
maxDurationnumberMaximum animation duration in seconds
meteorColorstringMeteor color — the bright head of the streak.
trailColorstringColour the tail fades OUT to, at the far end of the 120px streak. Defaults to `"transparent"`, which is the streak's natural falloff; pass a colour to have the tail land on it instead (e.g. a dim brand tint over a dark hero).
classNamestringAdditional CSS classes

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour
Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13)
Not focusable — no focus indicator required.
Reduced motion
Animation is gated on prefers-reduced-motion.
ARIA in the source
  • aria-hidden

Examples

3 more states from the same story file.

denseaceternity-starsbackground--dense ↗
slow twinkleaceternity-starsbackground--slow-twinkle ↗
with shooting starsaceternity-starsbackground--with-shooting-stars ↗

Dependencies

Base UI primitive
Native / no Base UI dependency
Lucide icons
none
NPM dependencies
none
Registry dependencies

Source

The full implementation — components/ui/aceternity/stars-background.tsx once installed.

599 lines · TypeScript
github ↗
"use client";

import { cn } from "@/lib/utils";

// @interlace/stars-background v1.1.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/stars-background
// What changed since: https://ds.interlace.tools/c/stars-background#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — StarsBackground, ShootingStars, Meteors
 *
 * Three night-sky layers you stack behind hero content: `StarsBackground`, a
 * canvas of density-seeded twinkling stars; `ShootingStars`, one SVG streak at
 * a time; and `Meteors`, CSS-animated tails falling at a fixed 215°.
 *
 * All three are `absolute inset-0` overlays and are meant to be composed —
 * `patterns/hero-cosmic.tsx` renders all three at once.
 *
 * Our reimplementation of the Aceternity UI starfield family. What is ours:

…579 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/stars-background.json