React Simple Animate

Common errors

• TypeError: Cannot read properties of undefined (reading 'onComplete') or onComplete callback not firing.

  cause A bug in the `useAnimate` hook prevented the `onComplete` callback from being called reliably in versions prior to 3.5.2.
  fix Update `react-simple-animate` to version `3.5.2` or newer.

• Animation not re-running or updating after state change when using `useAnimateKeyframes`.

  cause The `useAnimateKeyframes` hook failed to respond correctly to component state updates in versions prior to 3.3.11.
  fix Update `react-simple-animate` to version `3.3.11` or newer.

• Animations in `AnimateGroup` are overlapping or not playing in the correct sequence/timing.

  cause A bug in `AnimateGroup` affected the timing and delay mechanisms for sequenced animations in versions prior to 3.3.9.
  fix Update `react-simple-animate` to version `3.3.9` or newer.

Warnings

• breaking The type definition for the `Style` prop was updated in v3.4.0. If you were previously using custom type definitions for animation styles, they might no longer be compatible, as the prop is now strictly typed as `React.CSSProperties`.
  Fix: Ensure all style objects passed to animation props conform to `React.CSSProperties`.
• gotcha The `onComplete` callback within the `useAnimate` hook previously had a bug where it might not have fired correctly or consistently.
  Fix: Upgrade to `react-simple-animate@3.5.2` or higher to ensure `onComplete` callbacks function reliably with `useAnimate`.
• gotcha When using `useAnimateKeyframes`, there was a known issue where animations might not re-run or update correctly when component state changes.
  Fix: Upgrade to `react-simple-animate@3.3.11` or higher to ensure `useAnimateKeyframes` responds correctly to state updates.
• gotcha `AnimateGroup` had a bug affecting time delays between sequenced animations, potentially causing incorrect timing or overlaps.
  Fix: Upgrade to `react-simple-animate@3.3.9` or higher for correct time delay management within `AnimateGroup`.
• gotcha Ensure your React and React-DOM versions are compatible with the library's peer dependencies. Newer versions of `react-simple-animate` explicitly support React 17, 18, and 19.
  Fix: Install `react` and `react-dom` versions compatible with `^16.8.0 || ^17 || ^18 || ^19` as specified in the peer dependencies. For example, `npm install react react-dom`.

Install

• npm install react-simple-animate npm
• yarn add react-simple-animate yarn
• pnpm add react-simple-animate pnpm

Imports

• Animate
  wrong:

  import Animate from 'react-simple-animate'

  correct:

  import { Animate } from 'react-simple-animate'

  Animate is a named export component used for basic style A to B animations.
• useAnimate
  wrong:

  const useAnimate = require('react-simple-animate').useAnimate

  correct:

  import { useAnimate } from 'react-simple-animate'

  useAnimate is a named export hook for programmatic control over animations in functional components. Requires ESM import style.
• AnimateKeyframes
  wrong:

  import AnimateKeyframes from 'react-simple-animate'

  correct:

  import { AnimateKeyframes } from 'react-simple-animate'

  AnimateKeyframes is a named export component for applying CSS keyframe animations.
• AnimateGroup

  import { AnimateGroup } from 'react-simple-animate'

  AnimateGroup is a named export component for orchestrating multiple sequenced animations.

Quickstart

This example demonstrates the usage of `Animate`, `AnimateKeyframes`, and `AnimateGroup` components to create individual, keyframe, and sequenced UI animations in React.

import React from "react";
import { Animate, AnimateKeyframes, AnimateGroup } from "react-simple-animate";

export default () => (
  <>
    {/* animate individual element. */}
    <Animate play start={{ opacity: 0 }} end={{ opacity: 1 }}>
      <h1>React simple animate</h1>
    </Animate>
    
    {/* animate keyframes with individual element. */}
    <AnimateKeyframes
      play
      iterationCount="infinite"
      keyframes={["opacity: 0", "opacity: 1"]}
    >
      <h1>React simple animate with keyframes</h1>
    </AnimateKeyframes>
    
    {/* animate group of animation in sequences */}
    <AnimateGroup play>
      <Animate start={{ opacity: 0 }} end={{ opacity: 1 }} sequenceIndex={0}>
        first
      </Animate>
      <Animate start={{ opacity: 0 }} end={{ opacity: 1 }} sequenceIndex={1}>
        second
      </Animate>
      <Animate start={{ opacity: 0 }} end={{ opacity: 1 }} sequenceIndex={2}>
        third
      </Animate>
    </AnimateGroup>
  </>
);