Qwik Reveal ⚡️

Scroll and time-driven reveal animations for Qwik applications, based on modern web standards with graceful fallback for full browser compatibility.

• Introduction
  • Browser Support
  • Preview
• Get Started
  • Installation
  • Usage
  • Modes
  • Scroll Containers (Optional)
• Customisation
  • Attribute Reference
  • Class Reference
  • Animation Presets
  • Custom Properties (Variables)
• Troubleshooting

Browser Support

This library is supported by 96% of browsers.

Scroll-driven animations

Scroll-driven animations are supported by 78% of browsers and use the Scroll-driven Animations Module.

[!WARNING] Scroll-driven animations are unsupported by previous versions of Safari (v3-18) and Firefox.

The time-driven fallback is automatically used for these browsers.

Time-driven animations

Time-driven animations are supported by 96% of browsers and use the Intersection Observer API.

Preview

Get Started

Installation

1. Install

Install the @lgr.dev/qwik-reveal dependency using your preferred package manager.

npm install @lgr.dev/qwik-reveal

2. Load QwikReveal

Include the <QwikReveal/> component in a layout.tsx (e.g. the root src/routes/layout.tsx).

[!IMPORTANT] Loading <QwikReveal/> in root.tsx is not supported.

This library depends on the useLocation API to support client-side navigation (see more).

import { component$, Slot } from '@builder.io/qwik';
import { QwikReveal } from '@lgr.dev/qwik-reveal';

export default component$(() => (
  <>
    <QwikReveal/>
    <Slot/>
  </>
));

Usage

1. Reveal a single element

Individual elements can be animated by applying the reveal class directly to them.

<h2 class="reveal">Animates when scrolled into view</h2>

2. Reveal a group of elements

Groups of elements can be animated by applying the reveal-group class to their container.

<section class="reveal-group">
  <h2>Reveal together</h2>
  <p>Reveal together</p>
  <p>Reveal together</p>
</section>

You can optionally include the reveal-stagger class for a staggered reveal effect:

<section class="reveal-group reveal-stagger">
  <h2>Reveal first</h2>
  <p>Reveal second</p>
  <p>Reveal third</p>
</section>

3. Force time-driven animations

Force time-driven animations by including the reveal--time class, even for browsers that support scroll-driven animations.

<h2 class="reveal reveal--time">Animates once when scrolled into view</h2>

4. Repeat time-driven animations

Repeat time-driven animations each time an element is scrolled into view by including the reveal-repeat class.

<h2 class="reveal reveal-repeat">Animates repeatedly when scrolled into view</h2>

Modes

Animation modes can be configured for each target or container using the respective CSS class.

See the Browser Support section for more details.

Auto (default)

This is the default mode when no mode class is specified on an element or its container.

• Prefers scroll-driven animations when supported by the browser.
• Falls back to time-driven animations on older browsers.

<h2 class="reveal">Automatic</h2>

reveal--scroll

Forces scroll-driven animations regardless of browser compatibility.

• It is not recommended to explicitly set this.
• Forcing scroll-driven animations could lead to no animations being displayed in older browsers.

<h2 class="reveal reveal--scroll">Forces scroll-driven animation</h2>

reveal--time

Forces time-driven animations even on browsers which support scroll-driven animation.

• Set this for stylistic reasons;
• or if you prefer complete uniformity across browsers.

<h2 class="reveal reveal--time">Forces time-driven animation</h2>

Scroll Containers (Optional)

A common layout approach is to create a scroll container with multiple full-screen children.

When following this approach, include the data-reveal-root attribute on the scroll container.

export const Container = component$(() => (
  <main data-reveal-root class="overflow-y-auto h-full">
    ...
  </main>
));

And then include the reveal-screen class on each of the full-screen children that contain animated elements.

export const Container = component$(() => (
  <main data-reveal-root class="overflow-y-auto h-full">
    <section class="reveal-screen h-full">Screen One</section>
    <section class="reveal-screen h-full">Screen Two</section>
  </main>
));

Customisation

Attribute Reference

| Attribute Name | Description | |--------------------|---------------------------------------------------------------------------| | data-reveal-root | Declares an element as the scroll root for the time-driven scroll driver. |

Class Reference

| Class Name | Description | |---------------------------------|---------------------------------------------------------------------------------------| | Target | | | reveal | Declares a single element as an animation target. | | reveal-group | Declares a container whose direct children are animation targets. | | reveal-ignore | Exclude a child from group targeting. | | Stagger | | | reveal-stagger | Enables animation staggering within a targeted group. | | Mode | | | reveal--time | Forces time-driven animations even on browsers which support scroll-driven animation. | | reveal--scroll | Forces scroll-driven animations regardless of browser compatibility. | | Trigger (Time-driven) | | | reveal-trigger--self | | | Scope (Scroll-driven) | | | reveal-scope--screen | | | reveal-scope--view | | | Playback (Time-driven) | | | reveal-repeat | Replays the time-driven animation whenever the target leaves and re-enters the view. | | reveal-initial-animate | Animates the target even if already visible (i.e. above the fold). |

Animation Presets

| Class Name | Description | |----------------------------|-----------------------------------------| | Range | | | reveal-range--very-early | Animation begins and ends very early. | | reveal-range--early | Animation is earlier and more subtle. | | reveal-range--mid | Balanced animation (default). | | reveal-range--late | Animation is later and more pronounced. | | reveal-range--very-late | Animation begins and ends very late. | | From (Direction) | | | reveal-from--left | Animates in from the left. | | reveal-from--right | Animates in from the right. | | reveal-from--top | Animates in from the top. | | reveal-from--bottom | Animates in from the bottom. |

Custom Properties (Variables)

| Token Name | Description | |-------------------|-----------------| | Position | | | | |

Troubleshooting

• If scroll-driven reveals appear to do nothing, ensure you are not using overflow: hidden or overflow-x: hidden on html, body, or ancestors of the scroll container. Prefer overflow-x: clip instead.

• If scroll-driven animations complete before content becomes visible inside a full-height .screen, apply reveal-scope--view to that group, or move the stagger distribution later via the stagger min/max tokens.

• For grid sequences, force reveal--time to avoid awkward row/column inconsistencies in scroll mode.