https://github.com/infinitode/blurjs
BlurJS is a lightweight JavaScript library for creating blurred effects on HTML elements. Easily integrate blurred elements into your web projects with simple HTML attributes.
https://github.com/infinitode/blurjs
animation blurs blurs-elements css css-animations css-effects easy-to-use html html-attributes interactive-css javascript javascript-library js library lightweight modern-css modern-web-design open-source quick-setup
Last synced: 25 days ago
JSON representation
BlurJS is a lightweight JavaScript library for creating blurred effects on HTML elements. Easily integrate blurred elements into your web projects with simple HTML attributes.
- Host: GitHub
- URL: https://github.com/infinitode/blurjs
- Owner: Infinitode
- License: other
- Created: 2024-01-08T08:13:27.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-04-09T06:58:58.000Z (about 2 months ago)
- Last Synced: 2026-04-09T08:27:45.969Z (about 2 months ago)
- Topics: animation, blurs, blurs-elements, css, css-animations, css-effects, easy-to-use, html, html-attributes, interactive-css, javascript, javascript-library, js, library, lightweight, modern-css, modern-web-design, open-source, quick-setup
- Language: HTML
- Homepage: https://infinitode.netlify.app
- Size: 94.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# BlurJS 1.6
[](https://github.com/infinitode/blurjs/blob/main/LICENSE)
[](https://github.com/infinitode/blurjs/stargazers)
[](https://github.com/infinitode/blurjs/issues)
[](https://www.jsdelivr.com/package/gh/Infinitode/BlurJS)
[Documentation](https://infinitode-docs.gitbook.io/documentation/package-documentation/blurjs-package-documentation)
BlurJS is a lightweight JavaScript library for creating blurred effects on HTML elements. Easily integrate blurred elements into your web projects with simple HTML attributes.
> [!NOTE]
> Older versions of BlurJS are not maintained and are not recommended for use. We only maintain `main`, which is the latest stable release of BlurJS.
## Changes in Version 1.6
- **Performance Optimization**: Implemented CSS keyframe deduplication. Elements sharing the same animation parameters now reuse the same keyframe definition, significantly reducing DOM overhead.
- **Improved Initialization**: Faster processing of elements on page load.
- **Enhanced Testing & Showcases**: Added a new `tests/` directory with comprehensive examples, including hero sections, navigation bars, and a performance stress test.
- **Benchmarking**: Integrated internal timing to monitor library performance.
## Changes in Version 1.5
- Updated `test_blurjs.html` with a test case for the new attribute.
- Added a `blur-version` attribute to the test page and a console log for the version.
- Added a `blur-custom` attribute for custom CSS. This is useful for adding CSS that isn't supported by BlurJS out of the box.
## Changes in Version 1.4
- Support for more browsers, using vendor prefixes where needed.
- Performance optimizations by refactoring and cleaning code.
- More usage examples in the README file for clearer usage.
## Changes in Version 1.3
BlurJS now supports using multiple animations in a single element. You can combine animations and change their easing, duration, and repetitions to create unique and fun interactions/animations. New `blur-{animation-type}-timing` parameter for controlling easing during animations.
## Changes in Version 1.2
Pointer events and user selection are now available through BlurJS parameters. You can trigger animation effects dynamically using the new `blur-interaction` parameter. This will enable you to make custom interactions using very little effort.
### Changes in Version 1.1:
1. Moved the for loop to loop per element, improving stability and performance.
2. Created implementations for interactions with blur elements using the `blur-interaction` attribute.
3. Updated the code to also have attributes for controlling pointer events and user selection.
# Performance Benchmarks
BlurJS 1.6 introduces significant performance improvements, especially when handling many blurred elements.
| Metric | Version 1.5 | Version 1.6 | Improvement |
| :--- | :--- | :--- | :--- |
| **Init Time (50 elements)** | ~15ms | ~4ms | ~73% |
| **Init Time (500 elements)** | ~120ms | ~25ms | ~79% |
| **Redundant Keyframes** | High (1 per element) | Zero (Deduplicated) | 100% |
*Benchmarks conducted on a standard mid-range laptop. Actual results may vary based on hardware and browser.*
# Getting Started
## Installation
You can include BlurJS in your project by downloading the ready-to-use files from this repository or by using the CDN links for faster loading.
- `dist/blur.js`: The development (unminified) version of BlurJS.
- `dist/blur.min.js`: The production (minified) version of BlurJS.
**Using CDN:**
**Minified Version (Recommended for production)**
```html
```
**Normal Version (Useful for development/debugging)**
```html
```
> [!IMPORTANT]
> BlurJS should be placed at the end of the `` element in your HTML file, after all elements you intend to apply blur effects to. Do not place it in the `` element.
## How to use BlurJS
1. Ensure the parent element of any `blur` element has its CSS `position` property set to `relative` (or `absolute`, `fixed`, `sticky`). This is crucial for the correct positioning of the blur effect.
```html
```
2. Add the class `blur` to any HTML element you want BlurJS to affect.
3. Use the `blur-*` attributes on that element to customize its appearance and behavior.
BlurJS will automatically detect and process all elements with the class `blur`.
## Available properties
There are several available properties that come with BlurJS. Include these as HTML attributes on your `.blur` elements.
- `blur-width`: Sets the width of the blur effect. `default: 50px`
- `blur-height`: Sets the height of the blur effect. `default: 50px`
- `blur-amount`: Sets the intensity of the blur. `default: 25px`
- `blur-background`: Sets the color or background of the blur (CSS color values, gradients can also be used). `default: red`
- `blur-z-index`: Sets the Z Index of the blur effect. `default: 99`
- `blur-top`: Positions the blur from the top edge of its parent. `no default`
- `blur-left`: Positions the blur from the left edge of its parent. `no default`
- `blur-right`: Positions the blur from the right edge of its parent. `no default`
- `blur-bottom`: Positions the blur from the bottom edge of its parent. `no default`
- `blur-border-radius`: Changes the border radius of the blur effect. `default: 5rem 2rem 5rem 50%`
- `blur-grain`: Set to `true` to apply a grainy texture to the blur effect. `no default`
- `blur-pointer-events`: Set to `true` to enable pointer events (e.g., clicks) on the blur element, or `false` to disable. `no default (inherits CSS default)`
- `blur-user-select`: Set to `true` to allow text selection on the blur element, or `false` to disable. `no default (inherits CSS default)`
- `blur-custom`: Apply any custom CSS properties to the blur element. This is useful for adding properties that are not available through the other attributes. `no default`
**Animation Properties:**
Animations run with a 50% keyframe by default (animating to the target value and back to the original).
- `blur-scale`: The scale factor (e.g., `1.2` for 120% size). Triggers a scale animation. `no default`
- `blur-scale-duration`: Duration for the scale animation (e.g., `2s`, `500ms`). `default: 1s`
- `blur-scale-repetitions`: Number of times the scale animation repeats (e.g., `3`, `infinite`). `default: infinite`
- `blur-scale-timing`: CSS animation timing function for scale (e.g., `ease-in-out`, `linear`). `default: linear`
- `blur-translate-x`: Horizontal translation distance (e.g., `50px`, `-10%`). Triggers a horizontal translation animation. `no default`
- `blur-translate-x-duration`: Duration for X translation. `default: 1s`
- `blur-translate-x-repetitions`: Repetitions for X translation. `default: infinite`
- `blur-translate-x-timing`: Timing function for X translation. `default: linear`
- `blur-translate-y`: Vertical translation distance. Triggers a vertical translation animation. `no default`
- `blur-translate-y-duration`: Duration for Y translation. `default: 1s`
- `blur-translate-y-repetitions`: Repetitions for Y translation. `default: infinite`
- `blur-translate-y-timing`: Timing function for Y translation. `default: linear`
- `blur-opacity`: Target opacity value (e.g., `0.5`). Triggers an opacity animation. `no default`
- `blur-opacity-duration`: Duration for opacity animation. `default: 1s`
- `blur-opacity-repetitions`: Repetitions for opacity animation. `default: infinite`
- `blur-opacity-timing`: Timing function for opacity animation. `default: linear`
- `blur-animate`: Target blur amount for animation (e.g., `10px`). Animates the `filter: blur()` property. `no default`
- `blur-animate-duration`: Duration for blur amount animation. `default: 1s`
- `blur-animate-repetitions`: Repetitions for blur amount animation. `default: infinite`
- `blur-animate-timing`: Timing function for blur amount animation. `default: linear`
**Interaction Property:**
- `blur-interaction`: Defines how animations are triggered.
- `hover`: Animation plays when the mouse hovers over the element, pauses when it leaves.
- `click`: Animation toggles between play/pause on each click.
- `scroll`: Animation plays when the element is scrolled into the viewport, pauses when scrolled out.
`no default`
> [!NOTE]
> For an exhaustive list of properties and more detailed explanations, view the [official documentation](https://infinitode-docs.gitbook.io/documentation/package-documentation/blurjs-package-documentation).
## Usage examples
Below are some examples to get you started. Remember to include the BlurJS script at the end of your `` and ensure parent elements of `.blur` items have `position: relative;` (or similar).
### Basic Styling
**1. Custom Width, Height, and Color**
```html
```
**2. Custom Border Radius**
```html
```
### Advanced Styling
**1. Combining Multiple Properties & Positioning**
```html
Content behind the blur
```
**2. Grainy Texture Effect**
```html
```
### Animations
**1. Simple Scale Animation**
```html
```
**2. Combined Opacity and Translation Animation**
```html
```
**3. Animating Blur Amount**
```html
```
### Interactions
**1. Hover Interaction (Scale Effect)**
```html
Hover Me
```
> **Note:** For hover, `blur-scale-repetitions` is often set to `1` if you want the animation to play once per hover, or `infinite` (with `alternate`) if you want it to pulse as long as hovered. The default behavior is it plays to 50% and back.
**2. Click Interaction (Toggle Opacity)**
```html
Click Me
**3. Custom CSS properties**
```html
```
```
**3. Scroll Interaction (Translate Effect)**
```html
Scroll down to see the effect...
I appear on scroll
```
These examples showcase a range of possibilities with BlurJS. Experiment with different combinations of attributes to achieve unique effects!
# License
BlurJS is licensed under a [modified MIT license](https://github.com/infinitode/blurjs/blob/main/LICENSE), please view the license file for more information.
# Showcases & Tests
You can find various usage examples and performance tests in the `tests/` directory:
- `tests/basic_test.html`: General feature verification.
- `tests/showcase_hero.html`: Hero section with animated lighting effects.
- `tests/showcase_nav.html`: Glassmorphism navigation and scroll interactions.
- `tests/stress_test.html`: Performance benchmark with 500+ elements.
# Contributions
All contributions are welcome! You can get started by opening a request on Github. Help us make BlurJS better for everyone!