fluid-shader

fluid-shader is an ultra-lightweight, zero-dependency WebGL library to create stunning, interactive fluid gradients (often called Stripe-style gradients, mesh gradients, or Aurora backgrounds) for the web.

It comes as both a standard JavaScript controller and a native HTML5 Web Component, making it fully framework-agnostic (works out-of-the-box with React, Vue, Svelte, Tailwind CSS, or Vanilla HTML).

✦ Key Features

• Interactive Mouse Deflection: Eased mouse and touch deflection defers fluid coordinates away from cursor/finger movements dynamically.
• 12 Premium Presets: Load beautiful, pre-configured gradients (aurora, sunset, cotton, matrix, fire, ocean, forest, dusk, cyber, desert, nebula, peach) using a single parameter.
• Highly Configurable: Customise colors, flow speed, grain contrast, coordinate turbulence (warp), and deflection strength.
• Time Continuity: Dynamically change speeds or colors without abrupt visual skips or restarts.
• Zero Dependencies & Fast: Highly optimized WebGL shader running natively at 60 FPS.

✦ Installation

1. Package Manager (NPM / Yarn / PNPM)

npm install fluid-shader

2. CDN (Vanilla HTML / Direct Script Tag)

Use the library directly in the browser without bundlers:

<script src="https://cdn.jsdelivr.net/npm/fluid-shader@latest/dist/fluid-shader.umd.cjs"></script>

✦ Usage Guide

1. HTML5 Web Component

Once imported, the package registers a <fluid-shader> custom element that you can render anywhere:

Option A: Quick Presets (Easiest)

Get started instantly with one of the 12 built-in presets:

<!-- Load the green 'matrix' preset -->
<fluid-shader preset="matrix"></fluid-shader>

<!-- Load the 'sunset' preset but run it at custom speed -->
<fluid-shader preset="sunset" speed="0.15"></fluid-shader>

Option B: Fully Custom Options

<fluid-shader 
  colors="#05ccdd,#f2e666,#e6591a,#8c1acc,#1a40e6"
  speed="0.12"
  grain="0.04"
  warp="0.25"
  interaction="0.28"
  mouse-ease="0.08"
></fluid-shader>

Option C: Dynamic Attribute Updates

You can update attributes dynamically using JavaScript, and WebGL updates in real-time:

const element = document.querySelector('fluid-shader');

// WebGL shaders update dynamically via uniforms
element.setAttribute('speed', '0.05');
element.setAttribute('preset', 'cotton'); // Change preset on the fly

2. Vanilla JavaScript / Frameworks

For custom canvas integrations (React, Vue, Next.js, Svelte, Vite), use the raw FluidShader controller class directly on a <canvas> element:

import { FluidShader } from 'fluid-shader';

const canvas = document.getElementById('my-canvas');
const gradient = new FluidShader(canvas, {
  preset: 'aurora', // Load aurora preset defaults
  speed: 0.14 // Override default speed
});

// Update configurations dynamically
gradient.setOptions({
  preset: 'sunset',
  grain: 0.08
});

// Clean up WebGL resources when unmounting
gradient.destroy();

✦ Built-In Presets

Choose from the following clean and highly optimized color presets:

1. aurora - Neon Aurora (Cyan/Yellow/Orange/Purple/Blue)
2. sunset - Deep Sunset (Indigo/Violet/Rose/Orange)
3. cotton - Cotton Candy (Pastel Pink/Lavender/Sky Blue)
4. matrix - Cyber Matrix (Deep Forest Green/Lime)
5. fire - Warm Fire (Deep Red/Orange/Yellow)
6. ocean - Deep Ocean (Navy/Teal/Sky Blue)
7. forest - Misty Emerald (Forest Greens/Pale Green)
8. dusk - Lavender Sunset (Dreamy Purple/Lavender/Pastel)
9. cyber - Cyberpunk Neon (Hot Pink/Purple/Teal)
10. desert - Warm Pastel (Sand/Terracotta/Sage)
11. nebula - Cosmic Nebula (Deep Space Indigo/Magenta)
12. peach - Sakura Blossom (Soft Peach/Sakura Rose)

✦ API Options

| Attribute | JS Option | Type | Default | Description | | :--- | :--- | :--- | :--- | :--- | | preset | preset | string | undefined | Select from built-in presets (see list above). | | colors | colors | string \| array | Aurora Preset | Array of 5 colors (hex, rgb, or [r, g, b] floats). | | speed | speed | number | 0.12 | Controls gradient animation flow speed. | | grain | grain | number | 0.04 | Noise overlay grain intensity contrast. | | warp | warp | number | 0.25 | Noise coordinates turbulence/displacement strength. | | interaction | interaction | number | 0.28 | Eased mouse push deflection influence. | | mouse-ease | mouseEase | number | 0.08 | Mouse coordinate interpolation responsiveness. |

License

MIT