logo dile-components dile-components

DileScrollRevealMixin

Use this mixin to reveal elements progressively as the user scrolls. It finds the [data-reveal] and [data-reveal-group] elements inside a root (your component's shadow DOM by default), hides the ones below the fold and reveals them with a transition when they enter the viewport, using IntersectionObserver.

If you want to reveal the elements of a whole page, use the dile-scroll-reveal component, which applies this mixin to the document.

Installation

npm i @dile/ui

Usage

Extend your component with the mixin and include revealStyles in its styles:

import { LitElement, html } from 'lit';
import { DileScrollRevealMixin, revealStyles } from '@dile/ui/mixins/scroll-reveal';

class MyLanding extends DileScrollRevealMixin(LitElement) {
  static styles = [revealStyles];

  render() {
    return html`
      <h2 data-reveal>Fades in moving up</h2>
      <ul data-reveal-group>
        <li data-reveal="from-right">First</li>
        <li data-reveal="from-right">Second</li>
      </ul>
    `;
  }
}

The mixin starts after the first render and disconnects every observer when the component is removed from the page (it starts again if it is reconnected).

To orchestrate another root, override the revealRoot getter:

get revealRoot() {
  return document;
}

Markup API

Attribute Description
data-reveal The element fades in moving up.
data-reveal="from-right" / data-reveal="from-left" The element enters from the right / left.
data-reveal="trigger" The element is never hidden; it only gets the revealed state so your CSS can animate whatever you want.
data-reveal-offset="0.6" Overrides offset for this element or group (from 0 to less than 1).
data-reveal-group On a container: it decides when its sequence starts (using its own offset). Its descendant [data-reveal] elements are then revealed one after another in time, in document order, without waiting for more scroll.
data-reveal-stagger="300" On a group: milliseconds between its children. Defaults to groupStagger.
data-reveal-media="all" Overrides the enabling media query for this element or group.

Elements inside a group are driven by the group: they are not observed individually and their data-reveal-offset / data-reveal-media are ignored. Loose elements revealed in the same batch are staggered by stagger ms in document order. Each element is revealed only once. One IntersectionObserver is created per distinct offset.

Elements already past their offset line when the mixin starts are revealed immediately, without animation and before anything is hidden, so nothing flickers.

Properties

Property Type Default Description
media String "(min-width: 1024px)" Media query that enables the effect. When it doesn't match, elements are simply visible. Changing it re-evaluates the pending elements.
offset Number 0.15 Fraction of the viewport height, from the bottom, an element must have entered before it is revealed.
stagger Number 140 Milliseconds between loose elements revealed in the same batch.
groupStagger Number 220 Default milliseconds between the children of a group. Exposed via group-stagger.
watch Boolean false Watches the root with a MutationObserver to pick up elements added later (AJAX content, Lit re-renders, tab switches).

Getters

Methods

States and styles

The mixin sets these on each managed element:

revealStyles is a Lit css result with the base hide/show styles keyed on [data-reveal-state]; trigger elements are never hidden by it. The state lives on the elements themselves, so it works inside shadow DOM. Add your own rules on [data-reveal-state="pending"] / [data-reveal-state="revealed"] for project-specific effects.

Reduced motion

When the user has prefers-reduced-motion: reduce enabled, nothing is hidden or animated and every element is visible, regardless of media or data-reveal-media. The same happens when IntersectionObserver is not available.

CSS Custom Properties

Custom property Description Default
--dile-reveal-duration Duration of the reveal transition 0.7s
--dile-reveal-easing Easing of the movement cubic-bezier(0.22, 1, 0.36, 1)
--dile-reveal-distance Vertical distance travelled by data-reveal elements 1.75rem
--dile-reveal-distance-x Horizontal distance travelled by from-right / from-left elements 2.5rem
--dile-reveal-delay Set by the mixin on each element; used as transition delay 0ms

DileScrollRevealMixin demos

The effect is enabled at (min-width: 1024px) by default; this demo sets media="all" so it also works on small screens. Scroll down to see it.

Reveal inside a component

<script type="module">
  import { LitElement, html, css } from 'lit';
  import { DileScrollRevealMixin, revealStyles } from '@dile/ui/mixins/scroll-reveal/index.js';

  class ScrollRevealMixinDemo extends DileScrollRevealMixin(LitElement) {
    static styles = [
      revealStyles,
      css`
        :host {
          display: block;
          --dile-reveal-distance-x: 6rem;
        }
        section article {
          max-width: 320px;
        }
        article {
          padding: 1rem 1.25rem;
          margin-bottom: 1rem;
          border-radius: 12px;
          background: #eef4ff;
        }
      `,
    ];

    render() {
      return html`
        <article data-reveal>Revealed inside the shadow DOM of this component.</article>
        <section data-reveal-group data-reveal-stagger="250">
          <article data-reveal="from-left">Grouped 1</article>
          <article data-reveal="from-left">Grouped 2</article>
          <article data-reveal="from-left">Grouped 3</article>
        </section>
        <button type="button" @click=${() => this.revealAll()}>Reveal all</button>
      `;
    }
  }

  customElements.define('scroll-reveal-mixin-demo', ScrollRevealMixinDemo);
</script>
<scroll-reveal-mixin-demo media="all"></scroll-reveal-mixin-demo>