Quick Start
1. Add to your HTML <head>:
Code snippet omitted: it ships with the download.
2. Add the overlay as the FIRST thing inside <body>:
Code snippet omitted: it ships with the download.
3. Mark the elements that should stagger in after the curtain clears:
Code snippet omitted: it ships with the download.
4. Add before closing </body> tag:
Code snippet omitted: it ships with the download.
Options
All options go on the data-preloader overlay element.
| Attribute | Values | Default | Description |
|---|---|---|---|
data-preloader-duration |
Seconds | 2.4 |
How long the counter takes to reach 100 (or 90 in wait mode) |
data-preloader-once |
true, false |
false |
When true, the sequence runs once per browser session; repeat visitors skip straight to the page |
data-preloader-wait |
true, false |
false |
When true, the counter holds at 90 until the window load event fires, then sprints to 100 — the number reflects real asset loading |
data-preloader-exit |
wipe, split, iris, fade |
wipe |
Exit animation. wipe: twin panels wipe upward, front first, back chasing. split: the panels part sideways like doors, front sliding out left with the back chasing out right. iris: a circular opening grows from the centre of the screen. fade: the overlay fades out with a slight scale-up, quick and clean |
Element Hooks
| Attribute | Where | Description |
|---|---|---|
data-preloader |
The overlay | The root of the sequence; options live here |
data-preloader-panel |
Inside overlay | Curtain panels. They wipe upward in DOM order: first panel lifts first, second chases it. One panel also works |
data-preloader-count |
Inside overlay | Receives the padded counter text (000 to 100) |
data-preloader-bar |
Inside overlay | Scaled from scaleX(0) to scaleX(1) in sync with the counter |
data-preloader-fade |
Inside overlay | Overlay chrome (brand, count, bar) that lifts away before the curtain wipes |
data-preloader-reveal |
Anywhere in the page | Staggers in (rise + fade) as the overlay clears |
data-preloader-replay |
Any <button> |
Optional: clears the once-per-session flag and reloads the page to run the sequence again |
data-preloader-exit-override |
On a replay button | Optional: an exit style (wipe, split, iris, fade) to run on that reload. The click stores it in sessionStorage; on the next load the script reads and clears it, and it wins over data-preloader-exit for that one run |
The iris style needs no extra markup: the script writes the resolved exit style back onto the overlay's data-preloader-exit attribute, and the stylesheet's iris rule (a radial-gradient mask driven by a --iris variable, applied per panel) keys off it. The panels open in sequence, front first and back chasing, so the hole's edge is always the back panel's colour against your page and the opening reads as an expanding ring. An overlay built without panels irises as one piece instead.
Zero-Flash Setup (recommended)
The script adds a has-js class to <html> as its first statement, and all hiding CSS (.has-js .preloader, .has-js [data-preloader-reveal]) is gated behind it. Because the script loads at the end of <body>, an extremely slow connection could paint the page for a moment before it runs. To guarantee a zero-flash start, move that one line into your <head>:
Code snippet omitted: it ships with the download.
The line at the top of script.js is harmless to leave in place; adding a class twice does nothing.
Accessibility
- Reduced motion: with
prefers-reduced-motion: reducethe sequence never runs — the overlay is hidden and content is simply there. This is enforced twice: in CSS via the media query and in JavaScript viagsap.matchMedia. - No JavaScript: the overlay is
display: noneby default and reveal targets are only pre-hidden when thehas-jsclass is present, so the page renders as a plain readable document. - Screen readers: the counter is
aria-hidden(a number flashing to 100 is noise); a visually hiddenrole="status"element announces "Loading page" instead. - Scroll lock: scrolling is disabled only while the overlay is up and always released, including on the skip paths.
Dependencies
Required:
- GSAP 3.12+ (core only — no plugins)
Worked examples, the events and programmatic API, and the class reference ship with the download, alongside the full source.
