npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

viewport-animate

v1.0.0

Published

Easy and performant API for applying CSS animations when elements are scrolled into the viewport.

Downloads

14

Readme

npm version install size npm downloads Known Vulnerabilities

Features

  • Non-intrusive: Uses data attribute (data-va) by default.
  • Easily integrate with Animate.css.
  • Simple syntax for specifying duration, delay and number of iterations for each animation. Standard CSS animation syntax can be used to specify more animation properties.
  • Only play animations when elements are scrolled into the viewport, with a observer thresholds.
  • If desired, replay animations when elements are scrolled out of the viewport and back in.

Syntax

The library also supports a simplified syntax for specifying duration, delay and number of iterations for each animation:

attrib="<control><threshold> <animation-name> +<duration> -<delay> <iterations>x"

Example:

<p data-va="*0.01 fadeIn +1.5s -750ms 2.5x">
  When the element intersects the viewport by 1% of its height,
  play the fadeIn animation with a delay of 750ms and a duration of 1.5s,
  and loop 2.5 times. Also, repeat animation when the element is scrolled out
  of the viewport and back in (*).
</p>

Also, Tthe complete CSS animation syntax or any shorthand that works can be used to specify animation properties:

attrib="<control><threshold> <animation-name> <duration> <timing-function> <delay> <iterations> <direction> <fill-mode> <play-state> <timeline>"

Example:

<p data-va="@0.01 fadeIn 1.5s ease 750ms 2.5 normal none running auto">
  When the element intersects the viewport by 1% of its height,
  play the fadeIn animation with a delay of 750ms and a duration of 1.5s,
  and loop 2.5 times. Do not repeat animation when the element is scrolled out
  of the viewport and back in (*).
</p>
  • control is one of the following:
    • @ - Play animation once when the element is scrolled into the viewport. This is the default if you don't specify a control.
    • * - Play animation everytime the element intersects the viewport.
    • ! - Play the animation infinitely. This overrides the iterations value.
  • threshold is the percentage of the element's height that must intersect the viewport before the animation is played. Default is 0.01. See IntersectionObserver.thresholds. Multiple thresholds can be specified as a comma-separated list. e.g. 0.01,0.5,0.85.

Installation

Both ESM and UMD builds are available.

With a package manager

For environments like frontend frameworks (React, Vue, Svelte, Astro, etc.), you should use your preferred package manager to install the package:

npm

npm install viewport-animate

Bun

bun install viewport-animate

After installation, ViewportAnimate can be imported:

import { ViewportAnimate } from "viewport-animate";

See the demo Vue project for a complete example.

UMD (browser global)

For direct usage in browsers (plain HTML), you can conveniently load the UMD build directly from a CDN and ViewportAnimate will be available as window.ViewportAnimate:

Unpkg

<script src="https://unpkg.com/viewport-animate/umd.js"></script>

JSDelivr

<script src="https://cdn.jsdelivr.net/npm/viewport-animate/umd.js"></script>

See the demo HTML project for a complete example.

Example Usage (Plain HTML with Unpkg CDN)

Setup the CSS first. Load the animations from Animate.css via a CDN:

<link rel="stylesheet" href="https://unpkg.com/animate.css/animate.min.css" />

To ensure the animations are not visible before they are played, add the following CSS:

/* style.css */

[data-va] /* or whatever selector you use */
{
  opacity: 0;
}

... which you typically import as:

<link rel="stylesheet" href="styles.css" />

To ensure the elements are visible when JavaScript is disabled, add a separate CSS file:

/* no-js-style.css */

[data-va] /* or whatever selector you use */
{
  opacity: 1 !important;
}

... which you typically import as:

<noscript>
  <link rel="stylesheet" href="no-js-styles.css" />
</noscript>

Next, import the module from a CDN:

<script src="https://unpkg.com/viewport-animate/umd.js"></script>

... and then load the module:

<script>
  // Best to wait for the page to load before initializing
  window.addEventListener("load", () => {
    // Initialize with default options
    new ViewportAnimate({
      // if you change this, make sure to update the CSS selector above
      // and the data attribute below
      attribute: "data-va",

      // if threshold is unspecified in animation expression, then fallback
      // to when the element intersects the viewport by 1% of its height
      observerThreshold: 0.01,
    }).init();
  });
</script>

Finally, add the data-va attribute to the elements you want to animate:

Example:

<p data-va="*0.01 fadeIn +1.5s -750ms 2.5x">
  When the element intersects the viewport by 1% of its height,
  play the fadeIn animation with a delay of 750ms and a duration of 1.5s,
  and loop 2.5 times. Also, repeat animation when the element is scrolled out
  of the viewport and back in (*).
</p>

More Examples