Negotiate Pushing Milestone

    @wellyshen/use-web-animations
    TypeScript icon, indicating that this package has built-in type declarations

    0.9.1 • Public • Published

    USE-WEB-ANIMATIONS

    Using Web Animations API (a.k.a WAAPI) in the React hook way. Let's create highly-performant, flexible and manipulable web animations in the modern world. Hope you guys 👍🏻 it!

    ❤️ it? ⭐️ it on GitHub or Tweet about it.

    👀 Looking for a form library? Give React Cool Form a try!

    build status coverage status npm version npm downloads npm downloads gzip size MIT licensed All Contributors PRs welcome Twitter URL

    demo_basic

    ⚡️ Try yourself: https://use-web-animations.netlify.app

    demo_animate

    ⚡️ Try yourself: https://use-web-animations.netlify.app#animations

    Features

    Requirement

    To use use-web-animations, you must use react@16.8.0 or greater which includes hooks.

    Installation

    This package is distributed via npm.

    $ yarn add @wellyshen/use-web-animations
    # or
    $ npm install --save @wellyshen/use-web-animations

    Before We Start

    With the Web Animations API, we can move interactive animations from stylesheets to JavaScript, separating presentation from behavior. The API was designed based on the concept of the CSS Animations but there're still some differences between them. I strongly recommend you to read the documentation before we dive into this hook.

    Usage

    The API design of the hook not only inherits the DX of the Web Animations API but also provides useful features and sugar events to us. Here are some examples to show you how does it work.

    ⚠️ Most modern browsers support Web Animations API natively. You can also use polyfill for full browser support.

    Basic Usage

    Create an animation by the keyframes and animationOptions options (these are the parameters of the Element.animate()).

    💡 This hook supports the pseudoElement property via the animationOptions option.

    Edit useWebAnimations - basic

    import useWebAnimations from "@wellyshen/use-web-animations";
    
    const App = () => {
      const { ref, playState } = useWebAnimations({
        keyframes: {
          transform: "translateX(500px)", // Move by 500px
          background: ["red", "blue", "green"], // Go through three colors
        },
        animationOptions: {
          delay: 500, // Start with a 500ms delay
          duration: 1000, // Run for 1000ms
          iterations: 2, // Repeat once
          direction: "alternate", // Run the animation forwards and then backwards
          easing: "ease-in-out", // Use a fancy timing function
        },
        onReady: ({ playState, animate, animation }) => {
          // Triggered when the animation is ready to play
        },
        onUpdate: ({ playState, animate, animation }) => {
          // Triggered when the animation enters the running state or changes state
        },
        onFinish: ({ playState, animate, animation }) => {
          // Triggered when the animation enters the finished state
        },
        // More useful options...
      });
    
      return (
        <div className="container">
          <p>🍿 Animation is {playState}</p>
          <div className="target" ref={ref} />
        </div>
      );
    };

    For browsers that don't yet support the onReady and onFinish events, we can use the onUpdate to monitor the animation's state instead.

    let prevPending = true;
    
    const App = () => {
      const { ref } = useWebAnimations({
        // ...
        onUpdate: ({ playState, animation: { pending } }) => {
          if (prevPending && !pending) {
            console.log("Animation is ready to play");
          }
          prevPending = pending;
    
          if (playState === "finished") {
            console.log("Animation has finished playing");
          }
        },
      });
    
      // ...
    };

    Setting/Updating Animation

    The keyframes and animationOptions are cached when the hook is mounted. However, we can set/update the animation by the animation method.

    const { animation } = useWebAnimations();
    
    const changeAnim = () =>
      animation({
        keyframes: { transform: ["translateX(0)", "translateX(100px)"] },
        animationOptions: 1000,
        id: "123",
        playbackRate: 1,
        autoPlay: true,
      });

    Playback Control

    The shortcoming with existing technologies was the lack of playback control. The Web Animations API provides several useful methods for controlling playback: play, pause, reverse, cancel, finish, seek, control speed via the methods of the Animation interface. This hook exposes the animation instance for us to interact with animations, we can access it by the getAnimation() return value.

    Edit useWebAnimations - controls

    import useWebAnimations from "@wellyshen/use-web-animations";
    
    const App = () => {
      const { ref, playState, getAnimation } = useWebAnimations({
        playbackRate: 0.5, // Change playback rate, default is 1
        autoPlay: false, // Automatically starts the animation, default is true
        keyframes: { transform: "translateX(500px)" },
        animationOptions: { duration: 1000, fill: "forwards" },
      });
    
      const play = () => {
        getAnimation().play();
      };
    
      const pause = () => {
        getAnimation().pause();
      };
    
      const reverse = () => {
        getAnimation().reverse();
      };
    
      const cancel = () => {
        getAnimation().cancel();
      };
    
      const finish = () => {
        getAnimation().finish();
      };
    
      const seek = (e) => {
        const animation = getAnimation();
        const time = (animation.effect.getTiming().duration / 100) * e.target.value;
        animation.currentTime = time;
      };
    
      const updatePlaybackRate = (e) => {
        getAnimation().updatePlaybackRate(e.target.value);
      };
    
      return (
        <div className="container">
          <button onClick={play}>Play</button>
          <button onClick={pause}>Pause</button>
          <button onClick={reverse}>Reverse</button>
          <button onClick={cancel}>Cancel</button>
          <button onClick={finish}>Finish</button>
          <input type="range" onChange={seek} />
          <input type="number" defaultValue="1" onChange={updatePlaybackRate} />
          <div className="target" ref={ref} />
        </div>
      );
    };

    Getting Animation's Information

    When using the Web Animations API, we can get the information of an animation via the properties of the Animation interface. However, we can get the information of an animation by the getAnimation() return value as well.

    import useWebAnimations from "@wellyshen/use-web-animations";
    
    const App = () => {
      const { ref, getAnimation } = useWebAnimations({
        keyframes: { transform: "translateX(500px)" },
        animationOptions: { duration: 1000, fill: "forwards" },
      });
    
      const speedUp = () => {
        const animation = getAnimation();
        animation.updatePlaybackRate(animation.playbackRate * 0.25);
      };
    
      const jumpToHalf = () => {
        const animation = getAnimation();
        animation.currentTime = animation.effect.getTiming().duration / 2;
      };
    
      return (
        <div className="container">
          <button onClick={speedUp}>Speed Up</button>
          <button onClick={jumpToHalf}>Jump to Half</button>
          <div className="target" ref={ref} />
        </div>
      );
    };

    The animation instance isn't a part of React state, which means we need to access it by the getAnimation() whenever we need. If you want to monitor an animation's information, here's the onUpdate event for you. The event is implemented by the requestAnimationFrame internally and the event callback is triggered when the animation enters running state or changes state.

    import { useState } from "react";
    import useWebAnimations from "@wellyshen/use-web-animations";
    
    const App = () => {
      const [showEl, setShowEl] = useState(false);
      const { ref } = useWebAnimations({
        keyframes: { transform: "translateX(500px)" },
        animationOptions: { duration: 1000, fill: "forwards" },
        onUpdate: ({ animation }) => {
          if (animation.currentTime > animation.effect.getTiming().duration / 2)
            setShowEl(true);
        },
      });
    
      return (
        <div className="container">
          {showEl && <div className="some-element" />}
          <div className="target" ref={ref} />
        </div>
      );
    };

    Dynamic Interactions with Animation

    We can create and play an animation at the animationOptions we want by the animate method, which is implemented based on the Element.animate(). It's useful for interactions and the composite modes.

    Let's create a mouse interaction effect:

    Edit useWebAnimations - interaction

    import { useEffect } from "react";
    import useWebAnimations from "@wellyshen/use-web-animations";
    
    const App = () => {
      const { ref, animate } = useWebAnimations();
    
      useEffect(() => {
        document.addEventListener("mousemove", (e) => {
          // The target will follow the mouse cursor
          animate({
            keyframes: { transform: `translate(${e.clientX}px, ${e.clientY}px)` },
            animationOptions: { duration: 500, fill: "forwards" },
          });
        });
      }, [animate]);
    
      return (
        <div className="container">
          <div className="target" ref={ref} />
        </div>
      );
    };

    Create a bounce effect via lifecycle and composite mode:

    import useWebAnimations from "@wellyshen/use-web-animations";
    
    const App = () => {
      const { ref, animate } = useWebAnimations({
        id: "fall", // Set animation id, default is empty string
        keyframes: [{ top: 0, easing: "ease-in" }, { top: "500px" }],
        animationOptions: { duration: 300, fill: "forwards" },
        onFinish: ({ animate, animation }) => {
          // Lifecycle is triggered by each animation, we can check the id to prevent animation from repeating
          if (animation.id === "bounce") return;
    
          animate({
            id: "bounce",
            keyframes: [
              { top: "500px", easing: "ease-in" },
              { top: "10px", easing: "ease-out" },
            ],
            animationOptions: { duration: 300, composite: "add" },
          });
        },
      });
    
      return (
        <div className="container">
          <div className="target" ref={ref} />
        </div>
      );
    };

    ⚠️ Composite modes isn't fully supported by all the browsers, please check the browser compatibility carefully before using it.

    Use Built-in Animations

    Too lazy to think about animation? We provide a collection of ready-to-use animations for you, they are implemented based on Animate.css.

    👉🏻 Check out the demo.

    import useWebAnimations, { bounce } from "@wellyshen/use-web-animations";
    
    const App = () => {
      // Add a pre-defined effect to the target
      const { ref } = useWebAnimations({ ...bounce });
    
      return (
        <div className="container">
          <div className="target" ref={ref} />
        </div>
      );
    };

    We can customize the built-in animation by overriding its properties:

    const { keyframes, animationOptions } = bounce;
    const { ref } = useWebAnimations({
      keyframes,
      animationOptions: {
        ...animationOptions,
        delay: 1000, // Delay 1s
        duration: animationOptions.duration * 0.75, // Speed up the animation
      },
    });
    See all available animations

    Attention seekers

    • bounce
    • flash
    • pulse
    • rubberBand
    • shakeX
    • shakeY
    • headShake
    • swing
    • tada
    • wobble
    • jello
    • heartBeat

    Back entrances

    • backInDown
    • backInLeft
    • backInRight
    • backInUp

    Back exits

    • backOutDown
    • backOutLeft
    • backOutRight
    • backOutUp

    Bouncing entrances

    • bounceIn
    • bounceInDown
    • bounceInLeft
    • bounceInRight
    • bounceInUp

    Bouncing exits

    • bounceOut
    • bounceOutDown
    • bounceOutLeft
    • bounceOutRight
    • bounceOutUp

    Fading entrances

    • fadeIn
    • fadeInDown
    • fadeInDownBig
    • fadeInLeft
    • fadeInLeftBig
    • fadeInRight
    • fadeInRightBig
    • fadeInUp
    • fadeInUpBig
    • fadeInTopLeft
    • fadeInTopRight
    • fadeInBottomLeft
    • fadeInBottomRight

    Fading exits

    • fadeOut
    • fadeOutDown
    • fadeOutDownBig
    • fadeOutLeft
    • fadeOutLeftBig
    • fadeOutRight
    • fadeOutRightBig
    • fadeOutUp
    • fadeOutUpBig
    • fadeOutTopLeft
    • fadeOutTopRight
    • fadeOutBottomLeft
    • fadeOutBottomRight

    Flippers

    • flip
    • flipInX
    • flipInY
    • flipOutX
    • flipOutY

    Lightspeed

    • lightSpeedInRight
    • lightSpeedInLeft
    • lightSpeedOutRight
    • lightSpeedOutLeft

    Rotating entrances

    • rotateIn
    • rotateInDownLeft
    • rotateInDownRight
    • rotateInUpLeft
    • rotateInUpRight

    Rotating exits

    • rotateOut
    • rotateOutDownLeft
    • rotateOutDownRight
    • rotateOutUpLeft
    • rotateOutUpRight

    Specials

    • hinge
    • jackInTheBox
    • rollIn
    • rollOut

    Zooming entrances

    • zoomIn
    • zoomInDown
    • zoomInLeft
    • zoomInRight
    • zoomInUp

    Zooming exits

    • zoomOut
    • zoomOutDown
    • zoomOutLeft
    • zoomOutRight
    • zoomOutUp

    Sliding entrances

    • slideInDown
    • slideInLeft
    • slideInRight
    • slideInUp

    Sliding exits

    • slideOutDown
    • slideOutLeft
    • slideOutRight
    • slideOutUp

    Use Your Own ref

    In case of you had a ref already or you want to share a ref for other purposes. You can pass in the ref instead of using the one provided by this hook.

    const ref = useRef();
    const { playState } = useWebAnimations({ ref });

    Working in TypeScript

    This hook supports TypeScript, you can tell the hook what type of element you are going to animate through the generic type:

    const App = () => {
      const { ref } = useWebAnimations<HTMLDivElement>();
    
      return <div ref={ref} />;
    };

    💡 For more available types, please check it out.

    API

    const returnObj = useWebAnimations(options?: object);

    Return Object

    It's returned with the following properties.

    Key Type Default Description
    ref object Used to set the target element for animating.
    playState string | undefined Describes the playback state of an animation.
    getAnimation function Access the animation instance for playback control, animation's information and more.
    animate function Imperatively set/update the animation. Useful for interactive animations and composite animations.

    Parameter

    The options provides the following configurations and event callbacks for you.

    Key Type Default Description
    ref object For some reasons, you can pass in your own ref instead of using the built-in.
    id string "" Sets the ID of an animation, implemented based on the Animation.id.
    playbackRate number 1 Sets the playback rate of an animation, implemented based on the Animation.playbackRate.
    autoPlay boolean true Automatically starts the animation.
    keyframes Array | object An array of keyframe objects, or a keyframe object whose property are arrays of values to iterate over. See basic usage for more details.
    animationOptions number | object An integer representing the animation's duration (in milliseconds), or an object containing one or more timing properties. See basic usage for more details.

    | onReady | function | | It's invoked when an animation is ready to play. You can access the playState, animate and animation from the event object. | | onUpdate | function | | It's invoked when an animation enters the running state or changes state. You can access the playState, animate and animation from the event object. | | onFinish | function | | It's invoked when an animation enters the finished state. You can access the playState, animate and animation from the event object. |

    Use Polyfill

    Web Animations API has good support amongst browsers, but it's not universal. You'll need to polyfill browsers that don't support it. Polyfills is something you should do consciously at the application level. Therefore use-web-animations doesn't include it.

    Install web-animations-js:

    $ yarn add web-animations-js
    # or
    $ npm install --save web-animations-js

    Then import it at your app's entry point:

    import "web-animations-js/web-animations.min";

    You can read the document for more information.

    Articles / Blog Posts

    💡 If you have written any blog post or article about use-web-animations, please open a PR to add it here.

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Welly

    💻 📖 🚧

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i @wellyshen/use-web-animations

    DownloadsWeekly Downloads

    448

    Version

    0.9.1

    License

    MIT

    Unpacked Size

    110 kB

    Total Files

    7

    Last publish

    Collaborators

    • wellyshen