@russellio/vue-background-stars

Vue Background Stars

An animated starfield background component for Vue 3. It is intended for projects that need a lightweight, configurable night-sky effect without bringing in a canvas renderer or animation dependency.

Live demo

Contents

• Features
• Installation
• Usage
• API
• Styling
• Browser Support
• Development
• Contributing
• License

Features

• Vue 3 component with TypeScript definitions
• Configurable star count, density, color palette, and animation speed
• Per-layer weights to tune or remove individual star types
• Respects prefers-reduced-motion; animations can also be disabled with a prop
• Generates the star layers on mount with requestAnimationFrame
• Includes an optional ToggleSwitch component for simple visibility controls
• Ships ESM, UMD, CSS, and declaration files
• No runtime dependencies beyond Vue

Installation

npm install @russellio/vue-background-stars

yarn add @russellio/vue-background-stars

pnpm add @russellio/vue-background-stars

Usage

Import the component where you need the background — its styles come along automatically as a side effect of the import, no separate CSS import required.

<script setup lang="ts">
import { BackgroundStars } from '@russellio/vue-background-stars';
</script>

<template>
  <BackgroundStars />
</template>

The component renders as a fixed background with z-index: -1, so your page content should establish its own stacking context when needed.

<script setup lang="ts">
import { ref } from 'vue';
import { BackgroundStars, ToggleSwitch } from '@russellio/vue-background-stars';

const showStars = ref(true);
</script>

<template>
  <main class="page">
    <ToggleSwitch v-model="showStars" label="Starfield" />
    <BackgroundStars v-if="showStars" />

    <section class="content">
      <h1>Launch Console</h1>
    </section>
  </main>
</template>

<style scoped>
.page {
  position: relative;
  min-height: 100vh;
  color: white;
}
</style>

Plugin Install

You can register both components globally with the default plugin export.

import { createApp } from 'vue';
import VueBackgroundStars from '@russellio/vue-background-stars';
import App from './App.vue';

const app = createApp(App);

app.use(VueBackgroundStars);
app.mount('#app');

<template>
  <BackgroundStars />
  <ToggleSwitch v-model="showStars" label="Starfield" />
</template>

API

BackgroundStars

Renders the animated starfield. The component builds several box-shadow based layers from a single coordinate space, which keeps the DOM small while still allowing dense star patterns.

Props

layerWeights

Scales the number of stars generated for each layer independently. Valid layer names are exported as LAYER_NAMES:

tiny, small, med, large, bright, nebula, nebulaAux

Each value multiplies that layer's share of starCount. A weight of 0 removes the layer entirely — no element is rendered and no animation runs for it. Negative values are clamped to 0.

<script setup lang="ts">
import { BackgroundStars, type LayerWeights } from '@russellio/vue-background-stars';

// Plain starfield: no colored nebula glow at all.
const weights: LayerWeights = { nebula: 0, nebulaAux: 0 };
</script>

<template>
  <BackgroundStars :layer-weights="weights" />
</template>

Like starCount and density, layerWeights is read once when the layers are generated on mount. Changing it on a mounted component has no effect — bind a key that includes the weights to regenerate:

<BackgroundStars :key="JSON.stringify(weights)" :layer-weights="weights" />

Events

<BackgroundStars @background-ready="handleBackgroundReady" />

Examples

<template>
  <!-- Fewer stars -->
  <BackgroundStars :star-count="500" density="sparse" />

  <!-- More stars, slower blink animation -->
  <BackgroundStars density="dense" :speed="2" />

  <!-- Static background -->
  <BackgroundStars disable-animation />

  <!-- Custom nebula colors -->
  <BackgroundStars :palette="['#07121f', '#1d4ed8', '#38bdf8', '#f8fafc']" />

  <!-- Subtler nebula, no secondary glow band -->
  <BackgroundStars :layer-weights="{ nebula: 0.5, nebulaAux: 0 }" />

  <!-- Only the faint pinpoint stars -->
  <BackgroundStars :layer-weights="{ bright: 0, nebula: 0, nebulaAux: 0 }" />
</template>

ToggleSwitch

A small controlled switch component. It uses v-model and emits the standard update:modelValue event.

Props

Events

<script setup lang="ts">
import { ref } from 'vue';
import { ToggleSwitch } from '@russellio/vue-background-stars';

const enabled = ref(false);
</script>

<template>
  <ToggleSwitch v-model="enabled" label="Enable stars" />
</template>

Styling

Base styles load automatically when you import the components — bundlers (Vite, webpack, Next, Nuxt) pick up the stylesheet as a side effect of the JS import, so no separate CSS import is needed. If you're consuming the UMD build directly via a <script> tag with no bundler, the styles are injected into <head> at runtime instead. You can still override global selectors or set the toggle CSS variables from a wrapper, and @russellio/vue-background-stars/style.css remains available as an explicit import if you want a <link rel="stylesheet"> instead.

.my-page {
  --toggle-track-bg: #1f2937;
  --toggle-track-bg-active: #38bdf8;
  --toggle-thumb-bg: #f8fafc;
  --toggle-focus-ring: rgba(56, 189, 248, 0.45);
}

For background-specific changes, override the generated classes from your app stylesheet.

.sky {
  background: radial-gradient(at 50% 35%, #0f172a 0, transparent 55%), #020617;
}

.star-small,
.star-med,
.star-large,
.star-bright {
  opacity: 0.7;
}

The nebula glow is rendered as a set of heavily blurred box-shadow stamps that overlap into a diffuse band. As of 1.3.1 the blur radius is large enough that adjacent glows merge; previously they rendered as discrete orbs. Adjust the density of the band with layerWeights, and its intensity from your stylesheet:

.nebula-layer {
  opacity: 0.3; /* default: 0.55 */
}

Browser Support

The package targets modern browsers that support Vue 3, CSS animations, and standard ES module output. It is tested against the current versions of Chrome, Firefox, Safari, and Edge.

Development

Install dependencies:

npm install

Run the demo app:

npm run dev

Build the package:

npm run build

Run checks:

npm run type-check
npm run test:run
npm run lint
npm run format:check

Common scripts:

Build output is written to dist/ and includes:

• vue-background-stars.es.js
• vue-background-stars.umd.js
• vue-background-stars.css
• vue-background-stars.es.d.ts

Contributing

Issues and pull requests are welcome. For larger changes, open an issue first so the API or implementation direction can be discussed before code is written.

Before opening a pull request, please run the type check, tests, linting, and formatting check listed above. Updates that change runtime behavior should include tests and README updates where appropriate.

See CONTRIBUTING.md for the full contribution guide.

License

MIT. See LICENSE for details.

Credits

Built with Vue, Vite, and Vitest. Inspired by this CodePen.