Performance-First Scroll Animation Library – WavBlock

WavBlock is a lightweight JavaScript library that creates performant scroll-triggered animations using simple data attributes.

Features:

• Zero-dependency: Written in pure JavaScript with no external library requirements.
• Intersection Observer: Leverages the browser’s native IntersectionObserver API for efficient, performant scroll detection that doesn’t tank your Lighthouse scores.
• Declarative syntax: Animation behavior lives entirely in HTML data attributes. No JavaScript configuration needed for basic use cases.
• Built-in animations: Includes transitions like fade-up, fade-left, fade-right, scale-in alongside JavaScript-driven text animations like typewriter and letter-fade effects.
• Staggering support: Apply sequential animations to grouped elements with a single data-wavblock="stagger-children" declaration.
• Fully customizable: Control delay, duration, easing, and animation-specific parameters through data attributes.

See it in action:

How to use it:

1. Install & import the WavBlock package.

# NPM
$ npm install wavblock

import 'wavblock';

2. Or load the WavBlock’s JavaScript and CSS directly in the document.

<link rel="stylesheet" href="/dist/wavblock.min.css">
<script src="/dist/wavblock.min.js" defer></script>

3. Add the data-wavblock attribute to any element you want to animate. The library initializes automatically on DOMContentLoaded, so once you’ve included the script and styles, you’re ready to annotate your HTML.

<!-- Fades and slides the element up from the bottom. -->
<div data-wavblock="fade-up">
  <h2>Fade Up</h2>
  <p>This element will fade and slide up.</p>
</div>
<!-- Fades and slides the element down from the top. -->
<div data-wavblock="fade-down">
  <h2>Fade Down</h2>
  <p>This element will fade and slide down.</p>
</div>
<!-- Fades and slides the element in from the right. -->
<div data-wavblock="fade-left">
  <h2>Fade Left</h2>
  <p>This element will fade and slide in from the right.</p>
</div>
<!-- Fades and slides the element in from the left. -->
<div data-wavblock="fade-right">
  <h2>Fade Right</h2>
  <p>This element will fade and slide in from the left.</p>
</div>
<!-- Scales the element up from 0 to 1 with a fade. -->
<div data-wavblock="scale-in">
  <h2>Scale In</h2>
  <p>This element will scale into view.</p>
</div>

<!-- Reveals text by sliding it up from behind a mask. -->
<h2 data-wavblock="text-reveal">Text Reveal Effect</h2>
<!-- Fades in the text word-by-word. -->
<p data-wavblock="fade-in-text">
  These words will fade in one by one.
</p>
<!-- Simulates a classic typewriter effect with a cursor. -->
<h3 data-wavblock="typewriter" data-text="This is a typewriter effect."></h3>
<!-- A modern typewriter effect where each letter fades in. -->
<h3 data-wavblock="typewriter-fade" data-text="A modern typewriter fade."></h3>
<!-- Fades in each letter of the text sequentially. -->
<h3 data-wavblock="letter-fade">Letter Fade</h3>

<!-- Applies a sequential fade-up animation to the direct children. -->
<div class="card-container" data-wavblock="stagger-children" data-stagger-delay="150">
  <div class="card" data-wavblock="fade-up">
    <h3>Card 1</h3>
    <p>Appears first.</p>
  </div>
  <div class="card" data-wavblock="fade-up">
    <h3>Card 2</h3>
    <p>Appears 150ms after the first.</p>
  </div>
  <div class="card" data-wavblock="fade-up">
    <h3>Card 3</h3>
    <p>Appears 150ms after the second.</p>
  </div>
</div>

4. Customize the scroll animations with the following attributes:

data-delay

Sets a delay before the animation starts. The value can be in milliseconds (ms) or as a plain number (which is interpreted as ms).

<!-- This element will wait for 500ms before starting its fade-up animation. -->
<div data-wavblock="fade-up" data-delay="500ms">
  This content is delayed.
</div>

data-duration

Defines the total time the animation takes to complete. The value should be a valid CSS time unit (e.g., s or ms).

<!-- This scale-in animation will take 1.2 seconds to complete. -->
<div data-wavblock="scale-in" data-duration="1.2s">
  This animation is slower.
</div>

data-easing

Specifies a custom CSS transition-timing-function for the animation, controlling its acceleration curve.

<!-- This animation will use a custom 'ease-in-out' timing function. -->
<div data-wavblock="fade-right" data-easing="ease-in-out">
  This animation has custom easing.
</div>

data-speed

Controls the speed of JavaScript-driven text animations. For typewriter effects, it’s the delay between characters. For letter-fade, it’s the delay between each letter’s fade-in. The value is in milliseconds.

<!-- Each letter in this typewriter effect will appear every 50ms. -->
<h2 data-wavblock="typewriter" data-text="This is a fast typewriter." data-speed="50"></h2>

data-text

Overrides the inner content of an element for JavaScript-driven text animations. This is useful for keeping your HTML clean when the text is purely presentational.

<!-- The h2 will be empty, but the animation will display "Hello World". -->
<h2 data-wavblock="typewriter-fade" data-text="Hello World"></h2>

data-stagger-delay

Used with data-wavblock="stagger-children", this attribute sets the delay in milliseconds between each child’s animation, creating a sequential effect.

<!-- Each card will fade up 200ms after the previous one. -->
<div data-wavblock="stagger-children" data-stagger-delay="200">
  <div class="card" data-wavblock="fade-up">Card 1</div>
  <div class="card" data-wavblock="fade-up">Card 2</div>
  <div class="card" data-wavblock="fade-up">Card 3</div>
</div>