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
• 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 and stylesheet where you need the background.

<script setup lang="ts">
import { BackgroundStars } from '@russellio/vue-background-stars';
import '@russellio/vue-background-stars/style.css';
</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';
import '@russellio/vue-background-stars/style.css';

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 '@russellio/vue-background-stars/style.css';
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

| Prop | Type | Default | Description | | ------------------ | --------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------- | | starCount | number | 1000 | Base star count used to generate the layer sizes. | | palette | readonly string[] | built-in night-sky palette | Colors used for the nebula glow layers. | | density | 'sparse' \| 'normal' \| 'dense' | 'normal' | Multiplies the generated count by 0.4, 0.8, or 2. | | speed | number | 0.8 | Animation duration multiplier. Values above 1 are slower; values below 1 are faster. | | disableAnimation | boolean | false | Disables blinking animations, independent of reduced-motion settings. |

Events

| Event | Description | | ------------------ | ------------------------------------------------------------------------- | | background-ready | Emitted after the star layers are generated on the first animation frame. |

<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']" />
</template>

ToggleSwitch

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

Props

| Prop | Type | Default | Description | | ------------ | --------- | ------- | -------------------------------------------------------- | | modelValue | boolean | false | Current switch state. | | label | string | '' | Optional visible label. | | showIcon | boolean | true | Shows the decorative star icon on desktop-sized screens. |

Events

| Event | Description | | ------------------- | ------------------------------------------------------------ | | update:modelValue | Emitted with the next boolean state when the switch changes. |

<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

Importing @russellio/vue-background-stars/style.css is required. The components include their base styles, but you can still override global selectors or set the toggle CSS variables from a wrapper.

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

| Variable | Default | Used by | | -------------------------- | --------- | ---------------------- | | --toggle-track-bg | #d1d5db | Toggle track when off | | --toggle-track-bg-active | #3b82f6 | Toggle track when on | | --toggle-thumb-bg | #ffffff | Toggle thumb | | --toggle-focus-ring | #3b82f6 | Keyboard focus outline |

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;
}

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:

| Script | Description | | ----------------------- | ----------------------------------------- | | npm run dev | Starts the Vite demo app. | | npm run build | Type-checks and builds the package. | | npm run preview | Serves the production demo build locally. | | npm run type-check | Runs vue-tsc --noEmit. | | npm test | Starts Vitest in watch mode. | | npm run test:run | Runs Vitest once. | | npm run test:coverage | Runs Vitest with coverage. | | npm run lint | Runs ESLint over src/. |

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.