@bg-effects/grainient

✨ Beautiful noise-based gradient particle background effect for Vue 3.

✨ Features

• 🚀 High Performance - WebGL 2.0 based rendering, GPU accelerated
• 🎨 Rich Visuals - Noise-based gradient with grain texture
• 🌈 Color Palette - Support for 3-color gradients with 10+ presets
• 🎛️ Highly Customizable - 10+ adjustable parameters
• 🔧 Debug Panel - Built-in real-time configuration panel
• 🌍 i18n Support - Dual-language (Chinese/English) interface
• 📦 4 Built-in Presets - Ready-to-use color schemes
• 🎬 Animation Control - Adjustable speed (0.1x-5x)

📦 Installation

# pnpm
pnpm add @bg-effects/grainient

# npm
npm install @bg-effects/grainient

# yarn
yarn add @bg-effects/grainient

🚀 Quick Start

Basic Usage

<script setup>
import { Grainient } from '@bg-effects/grainient'
</script>

<template>
  <div class="container">
    <Grainient />
  </div>
</template>

<style scoped>
.container {
  width: 100vw;
  height: 100vh;
  position: relative;
}
</style>

With Debug Panel

<template>
  <Grainient debug lang="en" />
</template>

Custom Configuration

<script setup>
import { Grainient } from '@bg-effects/grainient'

const config = {
  color1: '#FF9FFC',
  color2: '#5227FF',
  color3: '#B19EEF',
  timeSpeed: 0.8,
  grainAmount: 0.06,
  contrast: 1.2,
  zoom: 0.9
}
</script>

<template>
  <Grainient v-bind="config" />
</template>

📖 API Reference

Props

Basic Settings

| Prop | Type | Default | Range | Description | |------|------|---------|-------|-------------| | timeSpeed | number | 0.6 | 0.1-5.0 | Animation speed multiplier | | grainAmount | number | 0.05 | 0-0.15 | Grain texture intensity | | zoom | number | 0.9 | 0.5-1.5 | Zoom level of the gradient |

Color Settings

| Prop | Type | Default | Description | |------|------|---------|-------------| | color1 | string | '#7aa2f7' | Primary color (hex format) | | color2 | string | '#020617' | Secondary color (hex format) | | color3 | string | '#bb9af7' | Tertiary color (hex format) |

Visual Effects

| Prop | Type | Default | Range | Description | |------|------|---------|-------|-------------| | contrast | number | 1.3 | 0.8-2.0 | Color contrast | | gamma | number | 1.0 | 0.5-2.0 | Gamma correction | | saturation | number | 1.0 | 0.5-1.5 | Color saturation | | rotation | number | 0 | 0-360 | Rotation angle in degrees | | blur | number | 0 | 0-3.0 | Blur intensity for dreamy effect |

Performance Settings

| Prop | Type | Default | Range | Description | |------|------|---------|-------|-------------| | quality | number | 0.75 | 0.5-2.0 | Render quality (DPR multiplier) | | maxFps | number | 60 | 30/60 | Maximum frame rate limit |

Advanced Settings (Internal)

| Prop | Type | Default | Description | |------|------|---------|-------------| | noiseScale | number | 2.0 | Noise pattern scale | | grainScale | number | 2.0 | Grain particle scale | | grainAnimated | boolean | true | Enable grain animation | | centerX | number | 0 | Horizontal center offset (-1 to 1) | | centerY | number | 0 | Vertical center offset (-1 to 1) | | colorBalance | number | 0 | Balance between color regions | | warpStrength | number | 0.5 | Warp distortion strength | | warpFrequency | number | 3 | Warp wave frequency | | warpSpeed | number | 1 | Warp animation speed | | warpAmplitude | number | 50 | Warp effect amplitude | | rotationAmount | number | 0 | Dynamic rotation amount | | blendAngle | number | 45 | Color blend angle | | blendSoftness | number | 0.1 | Color transition softness |

System Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | debug | boolean | false | Enable debug panel | | lang | string | 'zh-CN' | Debug panel language ('zh-CN' or 'en') | | className | string | - | Custom CSS class |

🎨 Presets

Four beautiful built-in presets are included:

Vibrant (活力四射)

Energetic blend of purple and gold tones with high contrast.

<Grainient 
  color1="#9a4c78" 
  color2="#f5cc36" 
  color3="#d2d283"
  :timeSpeed="0.8"
  :grainAmount="0.06"
  :contrast="1.2"
/>

Purple Gold (紫金交辉)

Luxurious purple and gold combination with warm glow.

<Grainient 
  color1="#f4cb37" 
  color2="#5a3f5f" 
  color3="#f5cc36"
  :timeSpeed="0.7"
  :grainAmount="0.05"
  :contrast="1.25"
/>

Blue (深海蓝韵)

Deep ocean-inspired blue gradient with cool tones.

<Grainient 
  color1="#020617" 
  color2="#1e293b" 
  color3="#3b82f6"
  :timeSpeed="0.6"
  :grainAmount="0.04"
/>

Pink (粉色梦境)

Soft pink dreamlike gradient with vibrant accents.

<Grainient 
  color1="#ff5f6d" 
  color2="#ffc371" 
  color3="#2193b0"
  :timeSpeed="0.5"
  :grainAmount="0.05"
/>

🎯 Usage Tips

Performance Optimization

Low-Power Mode (Mobile Devices)

<Grainient 
  :quality="0.5" 
  :maxFps="30"
  :grainAnimated="false"
  :grainAmount="0.03"
/>

Expected FPS: 30-60, significantly reduced battery consumption

Balanced Mode (Default)

<Grainient 
  :quality="0.75" 
  :maxFps="60"
/>

Expected FPS: 50-60, balanced performance and quality

High Quality Mode (Desktop)

<Grainient 
  :quality="1.5" 
  :maxFps="60"
  :grainAnimated="true"
/>

Expected FPS: 40-60, best visual quality

Quality Parameter Guide:

• 0.5 - Low quality, 25% pixel count, best performance
• 0.75 - Default, 56% pixel count, balanced
• 1.0 - Native resolution, 100% pixel count
• 1.5 - Enhanced, 225% pixel count
• 2.0 - Ultra, 400% pixel count (high-end devices only)

Responsive Design

<script setup>
import { computed } from 'vue'
import { Grainient } from '@bg-effects/grainient'

const isMobile = computed(() => window.innerWidth < 768)

const responsiveConfig = computed(() => ({
  grainAmount: isMobile.value ? 0.03 : 0.06,
  timeSpeed: isMobile.value ? 0.4 : 0.8
}))
</script>

<template>
  <Grainient v-bind="responsiveConfig" />
</template>

Dynamic Color Themes

<script setup>
import { ref, watch } from 'vue'
import { Grainient } from '@bg-effects/grainient'

const isDark = ref(true)

const colors = computed(() => 
  isDark.value 
    ? { color1: '#020617', color2: '#1e293b', color3: '#3b82f6' }
    : { color1: '#ff9ffc', color2: '#5227ff', color3: '#b19eef' }
)
</script>

<template>
  <Grainient v-bind="colors" />
  <button @click="isDark = !isDark">Toggle Theme</button>
</template>

Animation Control

<script setup>
import { ref } from 'vue'

const speed = ref(0.6)

function pause() {
  speed.value = 0
}

function play() {
  speed.value = 0.6
}

function speedUp() {
  speed.value = Math.min(speed.value + 0.2, 5)
}
</script>

<template>
  <Grainient :timeSpeed="speed" />
  <button @click="pause">⏸️</button>
  <button @click="play">▶️</button>
  <button @click="speedUp">⏩</button>
</template>

🔧 Development

# Install dependencies
pnpm install

# Build the package
pnpm -F @bg-effects/grainient build

# Watch mode
pnpm -F @bg-effects/grainient dev

🎨 Color Randomization

The effect uses a sophisticated color generation system:

• 30% chance - Select from 10 curated color palettes
• 70% chance - Generate harmonious colors using HSL color theory

This ensures both consistency and variety in the visual output.

⚡ Performance Notes

• WebGL 2.0 based - GPU accelerated rendering
• Responsive - Automatically adapts to container size changes
• Device pixel ratio - Capped at 2x for optimal performance
• Real-time updates - All parameters update dynamically

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

• Documentation
• Playground Demo
• GitHub Repository

Made with ❤️ using Vue 3 + WebGL 2.0