High-performance Animate On Scroll Library – Supersonic Plugin

Preview:

Description:

Supersonic Plugin is a super lightweight, high-performance JavaScript library designed for animating elements on scroll using CSS3 animations.

It’s built with TypeScript and utilizes IntersectionObserver API, so it only activates animations for elements currently visible on the screen. This means you can use it liberally without bogging down your site’s performance, even with tons of animated elements.

How to use it:

1. Install the Supersonic Plugin with NPM:

# NPM
$ npm install the-supersonic-plugin-for-scroll-based-animation

2. Import the Supersonic Plugin into your project.

import {
  TheSupersonicPlugin,
  Driver, // optional
  Animation // optional
} from "the-supersonic-plugin-for-scroll-based-animation"

3. Add CSS animations to your HTML elements and define “driver” elements that control the animation’s start and end points based on their position on the screen:

<div class="animatable-element supersonic-element">
  I'm an animatable element, start scrolling to see me animating
</div>
<div class="start supersonic-driver">
  I'm a driver, I start an animation when I appear
</div>
<div class="end supersonic-driver">
  I'm a driver, I finish an animation when I appear
</div>

.animatable-element {
  position: fixed;
  left: 50%;
  top: 50%;
  z-index: 10;
  translate: -50% 0 0;
  animation-name: animation;
  animation-duration: 10s; /* This is required */
  animation-play-state: paused; /* This is required, playback is controlled by plugin */
  animation-timing-function: linear; /* This is recommended so that your animation will be consistent */
  animation-fill-mode: forwards; /* This is recommended so that your animation holds last frame on finish */
}

const plugin = new TheSupersonicPlugin([
  {
    // Animation starts when this element appears on the screen
    start: '.start', 
    // Animation ends when this element appears on the screen
    end: '.end', 
    // List of elements with CSS animations
    elements: ['.animatable'] 
  },
]);

4. Available configuration options for the plugin.

const plugin = new TheSupersonicPlugin([
      /** Unique id of this running instance. You explicitly define it or let plugin auto generate it */
      id: string;
      /** Current window scrollY */
      scroll: number;
      /** Current screen height */
      screenHeight: number;
      /** Required to get all of the drivers render at once to stand on their first frame */
      renderedInitially: boolean;
      /** Used to cancelAnimationFrame on 'uninit()' */
      rafId: number;
      /** Color of console messages in dev mode. It changes each frame to make it more convenient to visually separate frames */
      consoleColor: string;
      /** IntersectionObserver instance */
      observer: Observer | null;
      /** Debounced resize listener */
      onResize: EventListener | null;
      /** You can store your custom data here to use between hooks */
      data: any;
      /** Make helper visible */
      debug: boolean;
      hooks: {
          onBeforeInit?: (plugin: TheSupersonicPlugin) => void;
          onAfterInit?: (plugin: TheSupersonicPlugin) => void;
          /** You can `return false` inside your hook, it will cancel rendering */
          onBeforeRender?: (plugin: TheSupersonicPlugin) => void | undefined | boolean;
          onAfterRender?: (plugin: TheSupersonicPlugin) => void;
          onBeforeResize?: (plugin: TheSupersonicPlugin) => void;
          onAfterResize?: (plugin: TheSupersonicPlugin) => void;
      };
      driverInstances: Map<string, Driver>;
      driverActiveInstances: Set<Driver>;
      constructor(drivers: DriverConfiguration[], configuration?: PluginConfiguration);
      /** Removes all of the plugin stuff (useful for SPA) */
      uninit(): void;
      /** Main rendering cycle. Active drivers are visible ones */
      render({ useActiveDrivers }: PluginRender): false | undefined;
      /** Updates global scroll and driver DOM elements top offset. Called once on page load and each time after window.resize */
      updateLimits(): void;
      updateScroll(): void;
      /** Dirty hack for calculating screen height. We can't just use "window.innerHeight" because it "jumps" on mobile phones when you scroll and toolbar collapses */
      updateScreenHeight(): void;
])

5. Available configuration options for the animations.

const animation = new Animation({
      id: string;
      cssAnimation: CSSAnimation;
      /** You can store your custom data here to use between hooks */
      data: any;
      /** Reference to linked `Driver` instance */
      driver: Driver;
      /** You can access domElement this animation is belongs to */
      domElement: HTMLElement;
      hooks: AnimationHooks;
      constructor({ id, cssAnimation, hooks, driver, domElement }: AnimationConstructor);
      render({ driverProgress }: AnimationRender): false | undefined;
})

6. Available configuration options for the drivers.

const driver = new Driver({
      id: string;
      /** Progress is generated by script and means how much of the scroll covered right now. Minimum value: 0, maximum value: 1, float number with 4 numbers after decimal point precision */
      progress: number;
      /** You can store your custom data here to use between hooks */
      data: any;
      /** Start is HTML element. When it appears on the screen, driver will start an animation */
      start: DriverBorder;
      /** End is HTML element. When it appears on the screen, driver will stop an animation */
      end: DriverBorder;
      /** Link to plugin instance to be able to access global variables like 'scroll', 'screenHeight' */
      plugin: TheSupersonicPlugin;
      animations: Map<string, Animation>;
      /** Helper is an element which need for IntersectionObserver to activate or deactive driver */
      helper: {
          /** DOM element which is dynamically generated by plugin */
          domElement: HTMLElement;
          pluginId: string;
          debug: boolean;
          constructor({ id, pluginId, debug }: DriverHelperConstructor);
          /** Sets position of helper */
          updateLimits({ top, height }: DriverHelperUpdateLimits): void;
          /** Deletes helper DOM element */
          uninit(): void;
      };
      hooks: {
          onBeforeInit?: (driver: Driver) => void;
          onAfterInit?: (driver: Driver) => void;
          /** You can `return false` inside your hook, it will cancel rendering */
          onBeforeRender?: (driver: Driver) => void | undefined | boolean;
          onAfterRender?: (driver: Driver) => void;
          onActivation?: (driver: Driver) => void;
          onDeactivation?: (driver: Driver) => void;
          onUpdateLimits?: (driver: Driver) => void;
      };
      constructor({ id, start, end, plugin, elements, hooks }: DriverConstructor);
      /** Driver calculates its progress and then renders all of it's properties with progress value */
      render({ scroll, renderedInitially, consoleColor }: DriverRender): false | undefined;
      /** Calculates current driver progress, depending on current scroll and top offset of DOM elements */
      calculateProgress({ scroll, start, end }: DriverCalculateProgress): number;
      /** Recalculates DOM elements top offset */
      updateLimits({ scroll, screenHeight }: DriverUpdateLimits): void;
      /** Activates driver when it becomes visible on the screen */
      activate(): void;
      /** Deactivates driver when it's progress becomes 0 or 1' */
      deactivate(): void;
})