vue-dynamic-bg

A zero-dependency dynamic background engine for Vue 3 — tunnel effects, parallax scrolling, and interactive backgrounds using Canvas 2D.

Features

• 🎨 Three templates: Dot Tunnel, Checkerboard Grid Tunnel, Parallax Scrolling
• ⚡ Zero runtime dependencies — pure Canvas 2D rendering
• 🔌 Dual API: Vue Components + Composables
• 🎮 Interactive: Mouse/touch follow + click ripple effects
• ⚙️ Configurable: Speed, colors, performance modes (high/medium/low)
• 📊 Debug mode: Built-in FPS monitor
• ♻️ Efficient: Object pooling, visibility-aware pause/resume, KeepAlive support
• 📦 Tiny: < 50KB minified+gzipped target

Installation

npm install vue-dynamic-bg

Quick Start

Component Style

<template>
  <DynamicBackground
    template="tunnel-dots"
    :speed="1.5"
    :mouse-follow="true"
    :color-a="'#00ff88'"
  >
    <!-- Your content renders on top of the background -->
    <div class="my-content">
      <h1>Hello World</h1>
    </div>
  </DynamicBackground>
</template>

<script setup lang="ts">
import { DynamicBackground } from 'vue-dynamic-bg'
</script>

Composable Style

<template>
  <div class="container">
    <canvas ref="canvasRef" />
    <div class="content">Your content here</div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useTunnelBackground } from 'vue-dynamic-bg'

const canvasRef = ref<HTMLCanvasElement>()

const {
  start,
  stop,
  setSpeed,
  setColorScheme,
} = useTunnelBackground(canvasRef, {
  template: 'tunnel-grid',
  speed: 2,
  mouseFollow: true,
})

onMounted(() => start())
onUnmounted(() => stop())

// KeepAlive support
onDeactivated(() => pause())
onActivated(() => resume())
</script>

Templates

| Template | Description | Visual | |----------|-------------|--------| | tunnel-dots | Op Art dot warp tunnel | ●●● perspective grid of circles | | tunnel-grid | Checkerboard pattern tunnel | ████ retro gaming style | | parallax | Multi-layer depth scrolling | ▓▓▓░░░ 2.5D parallax layers |

Props & Options

| Prop | Type | Default | Description | |------|------|---------|-------------| | template | 'tunnel-dots' \| 'tunnel-grid' \| 'parallax' | required | Background template type | | speed | number | 1 | Animation speed multiplier | | mouseFollow | boolean | true | Enable camera follows cursor | | clickRipple | boolean | true | Enable click ripple effect | | performance | 'high' \| 'medium' \| 'low' | 'medium' | Performance preset level | | colorA | string | '#ffffff' | Primary color | | colorB | string | — | Secondary color (checkerboard) | | debug | boolean | false | Show FPS overlay | | backgroundColor | string \| null | null | Canvas background fill |

Color Schemes

Built-in presets available via setColorScheme(name):

| Name | Colors | |------|--------| | mono | White / Gray | | redBlack | Red / Black | | cyanBlue | Cyan / Blue | | purplePink | Purple / Pink | | greenMatrix | Matrix Green | | gold | Gold / Bronze |

Development

# Install dependencies
npm install

# Run demo app
npm run dev

# Build library
npm run build

# Build and preview demo
npm run build:demo && npm run preview

License

MIT