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.
- 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.
BlurJS now supports using multiple animations in one 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.
Pointer events and user selection is 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.
- Moved the for loop to loop per element, improving stability and performance.
- Created implementations for interactions with blur elements using the
blur-interactionattribute. - Updated the code to also have attributes for controlling pointer events and user selection.
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)
<script src="https://cdn.jsdelivr.net/gh/Infinitode/BlurJS@main/dist/blur.min.js"></script>Normal Version (Useful for development/debugging)
<script src="https://cdn.jsdelivr.net/gh/Infinitode/BlurJS@main/dist/blur.js"></script>Important
BlurJS should be placed at the end of the <body> element in your HTML file, after all elements you intend to apply blur effects to. Do not place it in the <head> element.
- Ensure the parent element of any
blurelement has its CSSpositionproperty set torelative(orabsolute,fixed,sticky). This is crucial for correct positioning of the blur effect.<div style="position: relative; width: 200px; height: 200px; border: 1px solid #ccc;"> <!-- BlurJS elements will go here --> </div>
- Add the class
blurto any HTML element you want BlurJS to affect. - 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.
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: 50pxblur-height: Sets the height of the blur effect.default: 50pxblur-amount: Sets the intensity of the blur.default: 25pxblur-background: Sets the color or background of the blur (CSS color values, gradients can also be used).default: redblur-z-index: Sets the Z Index of the blur effect.default: 99blur-top: Positions the blur from the top edge of its parent.no defaultblur-left: Positions the blur from the left edge of its parent.no defaultblur-right: Positions the blur from the right edge of its parent.no defaultblur-bottom: Positions the blur from the bottom edge of its parent.no defaultblur-border-radius: Changes the border radius of the blur effect.default: 5rem 2rem 5rem 50%blur-grain: Set totrueto apply a grainy texture to the blur effect.no defaultblur-pointer-events: Set totrueto enable pointer events (e.g., clicks) on the blur element, orfalseto disable.no default (inherits CSS default)blur-user-select: Set totrueto allow text selection on the blur element, orfalseto disable.no default (inherits CSS 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.2for 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 thefilter: 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.
Below are some examples to get you started. Remember to include the BlurJS script at the end of your <body> and ensure parent elements of .blur items have position: relative; (or similar).
1. Custom Width, Height, and Color
<div style="position: relative; width: 150px; height: 100px; border: 1px solid #eee; margin-bottom: 10px;">
<div class="blur"
blur-width="100px"
blur-height="70px"
blur-background="rgba(0, 150, 255, 0.7)"
blur-amount="15px">
</div>
</div>2. Custom Border Radius
<div style="position: relative; width: 100px; height: 100px; border: 1px solid #eee; margin-bottom: 10px;">
<div class="blur"
blur-border-radius="50%"
blur-background="purple">
</div>
</div>1. Combining Multiple Properties & Positioning
<div style="position: relative; width: 250px; height: 150px; border: 1px solid #eee; margin-bottom: 10px; background: #f0f0f0;">
<p style="padding: 5px; text-align: center;">Content behind the blur</p>
<div class="blur"
blur-width="200px"
blur-height="100px"
blur-background="rgba(255, 100, 100, 0.6)"
blur-amount="20px"
blur-border-radius="10px"
blur-top="25px"
blur-left="25px"
blur-z-index="100">
</div>
</div>2. Grainy Texture Effect
<div style="position: relative; width: 150px; height: 100px; border: 1px solid #eee; margin-bottom: 10px;">
<div class="blur"
blur-width="120px"
blur-height="80px"
blur-background="rgba(50, 200, 50, 0.7)"
blur-grain="true"
blur-amount="30px">
</div>
</div>1. Simple Scale Animation
<div style="position: relative; width: 100px; height: 100px; border: 1px solid #eee; margin-bottom: 10px;">
<div class="blur"
blur-scale="1.5"
blur-scale-duration="2s"
blur-scale-repetitions="infinite"
blur-background="orange">
</div>
</div>2. Combined Opacity and Translation Animation
<div style="position: relative; width: 200px; height: 100px; border: 1px solid #eee; margin-bottom: 10px; overflow: hidden;">
<div class="blur"
blur-opacity="0.2"
blur-opacity-duration="3s"
blur-opacity-repetitions="infinite"
blur-translate-x="70px"
blur-translate-x-duration="3s"
blur-translate-x-timing="ease-in-out"
blur-translate-x-repetitions="infinite"
blur-background="teal">
</div>
</div>3. Animating Blur Amount
<div style="position: relative; width: 100px; height: 100px; border: 1px solid #eee; margin-bottom: 10px;">
<div class="blur"
blur-amount="5px"
blur-animate="35px"
blur-animate-duration="2.5s"
blur-animate-repetitions="infinite"
blur-background="crimson">
</div>
</div>1. Hover Interaction (Scale Effect)
<div style="position: relative; width: 120px; height: 120px; border: 1px solid #eee; margin-bottom: 10px; display: flex; align-items: center; justify-content: center;">
<p>Hover Me</p>
<div class="blur"
blur-interaction="hover"
blur-scale="2"
blur-scale-duration="0.5s"
blur-scale-timing="ease-out"
blur-scale-repetitions="1"
blur-background="rgba(255, 200, 0, 0.8)"
blur-width="80px"
blur-height="80px">
</div>
</div>Note: For hover,
blur-scale-repetitionsis often set to1if you want the animation to play once per hover, orinfinite(withalternate) 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)
<div style="position: relative; width: 120px; height: 120px; border: 1px solid #eee; margin-bottom: 10px; display: flex; align-items: center; justify-content: center; cursor: pointer;">
<p>Click Me</p>
<div class="blur"
blur-interaction="click"
blur-opacity="0.1"
blur-opacity-duration="1s"
blur-opacity-repetitions="1"
blur-background="rgba(0, 100, 200, 0.7)"
blur-width="100px"
blur-height="100px">
</div>
</div>3. Scroll Interaction (Translate Effect)
<div style="height: 150px;">Scroll down to see the effect...</div>
<div style="position: relative; width: 150px; height: 100px; border: 1px solid #eee; margin: 50vh auto 100vh auto; background: #f9f9f9;">
<!-- The large margin is to ensure scrolling is needed -->
<p style="text-align:center; padding-top: 40px;">I appear on scroll</p>
<div class="blur"
blur-interaction="scroll"
blur-translate-y="-30px"
blur-translate-y-duration="1.5s"
blur-translate-y-repetitions="1"
blur-background="rgba(100, 0, 150, 0.75)"
blur-width="100%"
blur-height="100%"
blur-top="0"
blur-left="0">
</div>
</div>These examples showcase a range of possibilities with BlurJS. Experiment with different combinations of attributes to achieve unique effects!
BlurJS is licensed under a modified MIT license, please view the license file for more information.
All contributions are welcome! You can get started by opening a request on Github. Help us make BlurJS better for everyone!