gradient-gl
v1.5.0
Published
Tiny WebGL library for procedural gradient animations. Deterministic. Seed-driven.
Maintainers
metaoryReadme
Easiest Usage:
One-Liner Script Tag
SeedScript
<script type="module" src="https://unpkg.com/gradient-gl?seed=a2.eba9"></script>Usage
npm install gradient-glimport gradientGL from 'gradient-gl'
// Mounts to <body>
gradientGL('a2.eba9')
// Mounts inside #app
gradientGL('a2.eba9', '#app')
// Access shader program if needed
const program = await gradientGL('a2.eba9')Mounting Behavior
- No selector: creates and styles a
<canvas>in<body> - Selector to an element: creates and styles a
<canvas>inside it - Selector to a
<canvas>: uses it directly, no styles or DOM changes
Styles are overridable.
Vite Configuration
export default {
build: {
target: 'esnext',
},
}CDN
UNPKG
<script type="module">
import gradientGL from 'https://unpkg.com/gradient-gl'
gradientGL('a2.eba9')
</script>ESM
<script type="module">
import gradientGL from 'https://esm.sh/gradient-gl'
gradientGL('a2.eba9')
</script>SeedScript Usage
<!-- Latest with default mounting point -->
<script type="module" src="https://unpkg.com/gradient-gl?seed=a2.eba9"></script>
<!-- optionally pin to a version @x.x.x -->
<script type="module" src="https://unpkg.com/[email protected]?seed=a2.eba9"></script>
<!-- optionally set the mount selector -->
<!-- mount inside the <main> tag -->
<script type="module" src="https://unpkg.com/gradient-gl?seed=a2.eba9&selector=main"></script>
<!-- mount inside the .wrapper>content -->
<!-- note: any valid css selector can be used -->
<script type="module" src="https://unpkg.com/gradient-gl?seed=a2.eba9&selector=.wrapper>.content"></script>
<!-- mount inside the #app -->
<!-- note hash needs to be escaped as %23 -->
<!-- #app → %23app -->
<script type="module" src="https://unpkg.com/gradient-gl?seed=a2.eba9&selector=%23app"></script>Seed Format
{shader}.{speed}{hue}{sat}{light}
- Shader:
[a-z][0-9](e.g.,a2) - Options:
[0-9a-f](hex values)
Explore and generate seeds in the playground
Performance
Animated Gradient Background Techniques
(Slowest → Fastest)
SVG– CPU-only, DOM-heavy, poor scaling, high memory usageCanvas 2D– CPU-only, main-thread load, imperative updatesCSS– GPU-composited, limited complexity, best for staticWebGL– GPU-accelerated, shader-driven, optimal balanceWebGPU– GPU-native, most powerful, limited browser support
[!NOTE] While WebGPU is technically the fastest, WebGL remains the best choice for animated gradients due to its maturity, broad support, and optimal performance/complexity ratio.
TODO: Interactive benchmark app