@boccdotdev/data-reveal

Declarative, scroll-triggered reveal animations driven by HTML data- attributes. Powered by GSAP + ScrollTrigger.

• Code-split — each animation type loads on demand. A page that only uses fade never downloads the split code (or its SplitText plugin).
• Zero side effects on import — nothing runs, and no GSAP is loaded, until you call init().
• Respects prefers-reduced-motion — elements snap to their final state instead of animating.

Install

npm install @boccdotdev/data-reveal gsap

gsap is a peer dependency (>=3.13.0) — you install it yourself so the package shares your single GSAP instance. GSAP 3.13+ ships ScrollTrigger and SplitText for free; no Club membership required.

Quick start

import { createReveal } from "@boccdotdev/data-reveal";

const reveal = createReveal();
await reveal.init();          // scan the document, load only the types in use

<h2 data-reveal="split" data-reveal-split="words">Animated headline</h2>
<div data-reveal="fade" data-reveal-direction="left">Fades in from the left</div>
<span data-reveal="counter" data-reveal-to="1200" data-reveal-separator=",">0</span>

That's it. Add a data-reveal attribute to any element and it animates as it scrolls into view.

How loading works

init() scans the container for [data-reveal], collects the set of types present, then dynamically import()s only those modules. Your bundler (Vite, webpack, etc.) splits each type into its own chunk, so the browser fetches code for an animation only when a page actually uses it. GSAP itself rides along in those chunks — a page with no reveals loads no GSAP.

Because loading is dynamic, init() is async. await it (or .then()) if you need to run code after reveals are set up.

Minimal builds (manual registration)

Auto mode is convenient, but to dynamically load any type on demand it has to reference every type — so your bundler emits a chunk file for all of them, even ones your site never uses. They're never downloaded unless present on a page, but the files still sit in your build output.

If you want only the types you use to exist in your build at all, import the /manual entry and register types explicitly. It has no reference to the auto-loader, so unused type modules (and their GSAP plugins) are never bundled:

import { createReveal } from "@boccdotdev/data-reveal/manual";
import { fade } from "@boccdotdev/data-reveal/fade";
import { scale } from "@boccdotdev/data-reveal/scale";

const reveal = createReveal({ types: [fade, scale] });
await reveal.init();

Each type is importable from its own subpath: @boccdotdev/data-reveal/{fade,scale,split,batch,blur,clip,rotate,slide,counter,parallax}. The HTML API is identical — data-reveal="fade" still works; you've just told the bundler which types are in play. A data-reveal type you didn't register is silently skipped.

The returned instance is the same as auto mode — init, refresh, destroy all behave identically. Choose auto for zero-config convenience, manual when build size matters.

API

const reveal = createReveal();

await reveal.init();              // scan document
await reveal.init(myContainer);   // scan a subtree only (any ParentNode)

reveal.refresh();                 // recompute all ScrollTrigger positions

reveal.destroy();                 // kill everything, revert SplitText, forget all elements
reveal.destroy(myContainer);      // kill + forget only reveals on/inside myContainer

init() is idempotent — already-initialized elements are skipped, so you can safely call it again as new content is added (e.g. infinite scroll).

refresh()

Recomputes every ScrollTrigger's start/end positions. ScrollTrigger already refreshes on window resize and load, but a JavaScript-driven layout change doesn't fire that — so call refresh() after toggling a grid's column count, opening an accordion, or when fonts/images finish loading and shift the page. Calls are coalesced to one refresh per frame, so it's cheap to call repeatedly.

destroy(container?)

With no argument, kills all tweens + ScrollTriggers, reverts SplitText, and forgets every element — a later init() re-runs the whole page. Pass a container to tear down only the reveals on or inside it; those elements are forgotten too, so re-adding content there and calling init() re-animates just that subtree. contains works on detached nodes, so you can pass a subtree you're about to remove. Use the scoped form for SPA partial swaps, the bare form for a full route change.

Animation types

All types accept these shared attributes:

| Attribute | Default | Notes | |-----------|---------|-------| | data-reveal-duration | varies | Seconds | | data-reveal-delay | 0 | Seconds | | data-reveal-start | top 85% | ScrollTrigger start position | | data-reveal-reverse | off | Add it to play the animation out again when scrolling back up past start. Default is play-once. (parallax is always bidirectional and ignores this.) |

fade

Fade + translate in.

| Attribute | Default | Values | |-----------|---------|--------| | data-reveal-direction | up | up down left right | | data-reveal-distance | 20 | px |

scale

Fade + scale up.

| Attribute | Default | Notes | |-----------|---------|-------| | data-reveal-from | 0.92 | Starting scale |

split

Per-character/word/line text reveal (uses SplitText).

| Attribute | Default | Values | |-----------|---------|--------| | data-reveal-split | chars | chars words lines | | data-reveal-stagger | 0.02 | Seconds between units |

batch

Staggered reveal of many children as they enter together. Targets elements marked data-reveal-item, or falls back to direct children.

| Attribute | Default | Notes | |-----------|---------|-------| | data-reveal-stagger | 0.06 | Seconds | | data-reveal-distance | 20 | px |

<ul data-reveal="batch">
  <li data-reveal-item>One</li>
  <li data-reveal-item>Two</li>
</ul>

blur

Fade in from a blur.

| Attribute | Default | Notes | |-----------|---------|-------| | data-reveal-blur | 12 | Starting blur in px |

clip

clip-path wipe reveal.

| Attribute | Default | Values | |-----------|---------|--------| | data-reveal-direction | up | up down left right (wipe direction) |

rotate

3D rotate in.

| Attribute | Default | Values | |-----------|---------|--------| | data-reveal-axis | x | x y z | | data-reveal-rotate | 90 | Degrees |

slide

Slide in from fully off the element's own box.

| Attribute | Default | Values | |-----------|---------|--------| | data-reveal-direction | up | up down left right |

counter

Count a number up as it enters view. Reads the target from data-reveal-to, or the element's text content.

| Attribute | Default | Notes | |-----------|---------|-------| | data-reveal-to | element text | Target number | | data-reveal-from | 0 | Starting number | | data-reveal-decimals | 0 | Decimal places | | data-reveal-separator | — | Thousands separator, e.g. , | | data-reveal-prefix | — | e.g. $ | | data-reveal-suffix | — | e.g. % |

parallax

Continuous, scroll-linked motion (scrubbed — not a one-shot reveal). Disabled under reduced motion.

| Attribute | Default | Notes | |-----------|---------|-------| | data-reveal-speed | 0.3 | Higher = more movement | | data-reveal-start | top bottom | ScrollTrigger start | | data-reveal-end | bottom top | ScrollTrigger end |

License

MIT