ChromaticBlur.js

A lightweight (2.1 KB gzipped), zero-dependency JavaScript plugin for creating stunning chromatic aberration blur effects using SVG filters.

Features

• 🎨 Beautiful chromatic aberration with color channel splitting
• 🪶 Zero dependencies - pure vanilla JavaScript
• ⚡ Tiny footprint (2.1 KB gzipped) and performant
• 🔧 Highly configurable
• 🔗 Method chaining support
• 🧹 Automatic cleanup and memory management
• 📦 Multiple module formats (ES6, CommonJS, AMD, Global)

Installation

Via CDN (Recommended)

<!-- Minified version (6.4 KB, 2.1 KB gzipped) -->
<script type="module">
  import ChromaticBlur from 'https://unpkg.com/[email protected]/dist/chromatic-blur.min.js';
  const blur = new ChromaticBlur('.element');
</script>

<!-- Development version with comments (10.5 KB) -->
<script type="module">
  import ChromaticBlur from 'https://unpkg.com/[email protected]/dist/chromatic-blur.js';
</script>

Via npm

npm install chromatic-blur

import ChromaticBlur from 'chromatic-blur';

Quick Start

// Basic usage
const blur = new ChromaticBlur('.my-element');

// With custom options
const blur = new ChromaticBlur('.navbar', {
  redOffset: 8,
  blueOffset: -8,
  blurAmount: 5
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | redOffset | number | 5 | Red channel offset in pixels (positive = right) | | blueOffset | number | -5 | Blue channel offset in pixels (negative = left) | | blurAmount | number | 3 | Gaussian blur standard deviation | | turbulenceFrequency | number | 0.001 | Turbulence noise frequency (lower = smoother) | | displacementScale | number | 50 | Displacement map scale for wavy distortion | | borderColor | string | 'rgba(156, 156, 156, 0.2)' | Border color for glass effect | | addOverlay | boolean | true | Add gradient overlay layer | | addNoise | boolean | true | Add noise overlay layer |

API Methods

Instance Methods

update(options)

Update effect options dynamically. Returns this for chaining.

blur.update({ redOffset: 10, blurAmount: 6 });

enable()

Enable the effect (if previously disabled). Returns this for chaining.

blur.enable();

disable()

Temporarily disable the effect. Returns this for chaining.

blur.disable();

destroy()

Remove the effect and cleanup all resources.

blur.destroy();

Static Methods

ChromaticBlur.destroyAll()

Cleanup all instances. Useful for Single Page Applications.

ChromaticBlur.destroyAll();

Usage Examples

Basic Navigation Bar

const nav = new ChromaticBlur('.navbar', {
  redOffset: 5,
  blueOffset: -5,
  blurAmount: 3
});

Intense Effect

const hero = new ChromaticBlur('.hero-section', {
  redOffset: 15,
  blueOffset: -15,
  blurAmount: 8,
  displacementScale: 100
});

Minimal Glass Effect

const card = new ChromaticBlur('.card', {
  redOffset: 2,
  blueOffset: -2,
  blurAmount: 2,
  addNoise: false,
  addOverlay: false
});

Method Chaining

const blur = new ChromaticBlur('.element')
  .update({ blurAmount: 5 })
  .enable();

// Later...
blur.disable().update({ redOffset: 10 }).enable();

Dynamic Control

const blur = new ChromaticBlur('.navbar');

// Adjust based on scroll position
window.addEventListener('scroll', () => {
  const scrollPercent = window.scrollY / document.body.scrollHeight;
  blur.update({
    blurAmount: 3 + (scrollPercent * 10),
    redOffset: 5 + (scrollPercent * 10)
  });
});

Cleanup in SPAs

// React useEffect example
useEffect(() => {
  const blur = new ChromaticBlur('.navbar');

  return () => {
    blur.destroy(); // Cleanup on unmount
  };
}, []);

// Or cleanup all instances at once
ChromaticBlur.destroyAll();

Browser Support

Works in all modern browsers that support:

• SVG filters
• CSS backdrop-filter (with -webkit- prefix for Safari)

For best results, ensure background content has sufficient contrast.

Modern Best Practices Implemented

• ✅ ES6+ Class-based architecture - Clean, maintainable OOP design
• ✅ No dependencies - Pure vanilla JavaScript (2.1 KB gzipped)
• ✅ Declarative API - Intuitive method names and options
• ✅ Method chaining - Fluent interface pattern
• ✅ Automatic cleanup - Prevents memory leaks
• ✅ TypeScript-friendly - Comprehensive JSDoc comments
• ✅ Multiple module formats - Works everywhere
• ✅ Performance optimized - Reuses SVG filters, minimal DOM manipulation

Performance Tips

1. Reuse instances - Don't create multiple instances for the same element
2. Cleanup properly - Always call destroy() when removing elements
3. Moderate settings - Higher values for blur/displacement are more expensive
4. Limit instances - Each instance creates an SVG filter; use sparingly

License

MIT License - feel free to use in personal and commercial projects!

Credits

Created as a demonstration of modern vanilla JavaScript plugin development.