retransition

A library that helps you create smooth transitions in your react app.

Usage no npm install needed!

<script type="module">
  import retransition from 'https://cdn.skypack.dev/retransition';
</script>

README

Retransition

GitHub npm npm bundle size Codecov

A library that helps you create smooth transitions in your react app.

| English | Russian |

Features

  • Automatic transition/animation end detection
  • List animations with FLIP technique
  • React strict mode compatible
  • Small size (<2.8kb minified gzipped)
  • TypeScript support out of the box

Motivation

I decided to create this package because often used react-transition-group but I didn't like some things about it. For instance, you have to pass timeout or provide your custom addEndListener. Also, you don't have a "move" transition for <TransitionGroup /> and it's not strict mode compatible.

Installation

npm:

npm i retransition

or yarn:

yarn add retransition

Note that this library uses hooks, so you need to have react and react-dom 16.8.0 or higher.

Getting started

Basic example

Try in codesandbox

import React, { useState } from "react";
import { Transition } from "retransition";

import "./index.css";

const App = () => {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <button onClick={() => setVisible(v => !v)}>Toggle</button>
      <Transition visible={visible} name="fade">
        <div style={{ height: 200, width: 200, background: "black" }}></div>
      </Transition>
    </>
  );
};
.fade-leave-to,
.fade-enter-from {
  opacity: 0;
  transform: translateX(300px);
}

.fade-enter-active,
.fade-leave-active {
  transition: all 500ms ease;
}

.fade-leave-from,
.fade-enter-to {
  opacity: 1;
  transform: translateX(0);
}

Let's dive deeper into this example and understand what happens under the hood.

When you change the visible prop of the <Transition> component, it will show or hide the child element according to it. But it won't do it immediately. Entering and Leaving will be done in 3 steps:

  1. At the step first element would be inserted into the DOM if it's enter transition. fade-(enter|leave)-from and fade-(enter|leave)-active classes would be added.
  2. On the next frame (once the browser was able to rerender the screen and apply new styles) we remove fade-(enter|leave)-from class and add fade-(enter|leave)-to class. If classes are written correctly, this should trigger a transition.
  3. Once the transition is finished, we remove fade-(enter|leave)-active and fade-(enter|leave)-to classes. The element would be removed from the DOM if it's a leave transition.

CSS Animation

Although CSS transitions are more common and simpler, there are some situations where they don't give you enough control. That's why this library also supports CSS animations.

Try in codesandbox

import React, { useState } from "react";
import { Transition } from "retransition";

import "./index.css";

const App = () => {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <button onClick={() => setVisible(v => !v)}>Toggle</button>
      <Transition visible={visible} name="fade-animation">
        <div style={{ height: 200, width: 200, background: "black" }}></div>
      </Transition>
    </>
  );
};
.fade-animation-enter-active {
  animation: rotate-in 500ms ease;
}

.fade-animation-leave-active {
  animation: rotate-in 500ms ease reverse;
}

@keyframes rotate-in {
  0% {
    transform: scale(0) rotate(360deg);
  }
  70% {
    transform: scale(1.3) rotate(-108deg);
  }
  100% {
    transform: scale(1) rotate(0);
  }
}

Transition type

Sometimes you may want to have transition and animation on the same element. This library will pick the one that has a longer duration to detect the end of the transition. But this may not be the case in some situations. For instance, if you have animation on initial render and transition on mouseover. In these cases, you have to manually pass about which type <Transition> component should care about.

<Transition type="animation" {...props}>
  {/* ... */}
</Transition>

Unmounting

Be default your child element/component will be unmounted on leave. But if you want it to be hidden with display: none, you could pass umount prop as false.

<Transition name="fade" visible={visible} unmount={false}>
  <div>I'm always in the DOM</div>
</Transition>

Transitions on Initial Render

By default, your transition won't run on the initial render. If you want to change it, pass appear prop.

<Transition name="fade" visible={visible} appear>
  {/* ... */}
</Transition>

Note that you could just pass appear without any value and it'd be equivalent to appear={true}

This will result in having enter transition on initial render. But if you want custom transition (different classes and events) for the initial render you could pass customAppear. In this case ${name}-appear-from, ${name}-appear-active and ${name}-appear-to classes would be generated.

<Transition name="fade" visible={visible} appear customAppear>
  {/* ... */}
</Transition>

Custom classes

If you don't want your classes to be generated from the name, you could pass your classes through props. They'll override generated classes.

<Transition
  name="fade"
  enterFromClass="class-1"
  enterActiveClass="class-2"
  enterToClass="class-3"
  leaveFromClass="class-4"
  leaveActiveClass="class-5"
  leaveToClass="class-6"
  appearFromClass="class-7"
  appearActiveClass="class-8"
  appearToClass="class-9"
>
  {/* ... */}
</Transition>

JavaScript Events

<Transition> provides javascript events for each phase of a transition.

<Transition
  name="fade"
  visible={visible}
  onBeforeEnter={onBeforeEnter}
  onEnter={onEnter}
  onAfterEnter={onAfterEnter}
  onBeforeLeave={onBeforeLeave}
  onLeave={onLeave}
  onAfterLeave={onAfterLeave}
  // only works with `customAppear`
  onBeforeAppear={onBeforeAppear}
  onAppear={onAppear}
  onAfterAppear={onAfterAppear}
>
  {/* ... */}
</Transition>

List Transitions

We've been working with single elements so far. But what if you want to animate enter/leave of list items?. That's where you should use <TransitionGroup>. It's like a state machine that detects an item addition/removal and passes correct props to <Transition> component.

Try in codesandbox

import React, { useState } from "react";
import { Transition, TransitionGroup } from "retransition";

import "./index.css";

const getRandomIndex = length => Math.floor(Math.random() * length);

const initialNumbers = new Array(10)
  .fill(null)
  .map((_, i) => ({ value: i, index: Math.random() }));

const App = () => {
  const [numbers, setNumbers] = useState(initialNumbers);

  const add = () => {
    const index = getRandomIndex(numbers.length);
    const newNum = {
      value: numbers.length,
      index: Math.random(),
    };
    const newValue = [
      ...numbers.slice(0, index),
      newNum,
      ...numbers.slice(index),
    ];
    setNumbers(newValue);
  };

  const remove = () => {
    const index = getRandomIndex(numbers.length);
    const newValue = numbers.filter((_, idx) => idx !== index);
    setNumbers(newValue);
  };

  return (
    <>
      <button onClick={add} style={{ marginRight: 5 }}>
        Add
      </button>
      <button onClick={remove} style={{ marginRight: 5 }}>
        Remove
      </button>
      <div>
        <TransitionGroup name="fade">
          {numbers.map(n => (
            <Transition key={n.index}>
              <div style={{ padding: 5 }}>{n.value}</div>
            </Transition>
          ))}
        </TransitionGroup>
      </div>
    </>
  );
};
.fade-leave-to,
.fade-enter-from {
  transform: translateX(200px);
  opacity: 0;
}

.fade-enter-active,
.fade-leave-active {
  transition: opacity 500ms ease, transform 500ms ease;
}

.fade-leave-active {
  /* 
    note that we add absolute position to leaving element
    so other elements change their position and trigger move transition 
  */
  position: absolute;
}

.fade-leave-from,
.fade-enter-to {
  transform: translateX(0);
  opacity: 1;
}

Note that you can pass a name to your <TransitionGroup> and it will be used also for its children <Transition> components.

List Move Transition

There is one problem with our previous example. When the item gets added/removed, other ones just snap into their new position. Let's see how we can fix it.

<TransitionGroup> adds ${name}-move class to its children whenever they change their position. Let's tweak our previous example a little bit and see what we can do with it.

Try in codesandbox

import React, { useState } from "react";
import { Transition, TransitionGroup } from "retransition";
+import { shuffle } from "lodash-es";

import "./index.css";

const getRandomIndex = length => Math.floor(Math.random() * length);

const initialNumbers = new Array(10)
  .fill(null)
  .map((_, i) => ({ value: i, index: Math.random() }));

const App = () => {
  const [numbers, setNumbers] = useState(initialNumbers);

  const add = () => {
    const index = getRandomIndex(numbers.length);
    const newNum = {
      value: numbers.length,
      index: Math.random(),
    };
    const newValue = [
      ...numbers.slice(0, index),
      newNum,
      ...numbers.slice(index),
    ];
    setNumbers(newValue);
  };

  const remove = () => {
    const index = getRandomIndex(numbers.length);
    const newValue = numbers.filter((_, idx) => idx !== index);
    setNumbers(newValue);
  };

+ const reorder = () => {
+   setNumbers(n => shuffle(n));
+ };

  return (
    <>
      <button onClick={add} style={{ marginRight: 5 }}>
        Add
      </button>
      <button onClick={remove} style={{ marginRight: 5 }}>
        Remove
      </button>
+     <button onClick={reorder} style={{ marginRight: 5 }}>
+       Shuffle
+     </button>
      <div>
        <TransitionGroup name="fade">
          {numbers.map(n => (
            <Transition key={n.index}>
              <div style={{ padding: 5 }}>{n.value}</div>
            </Transition>
          ))}
        </TransitionGroup>
      </div>
    </>
  );
};
.fade-leave-to,
.fade-enter-from {
  transform: translateX(200px);
  opacity: 0;
}

.fade-enter-active,
.fade-leave-active {
  transition: opacity 500ms ease, transform 500ms ease;
}

.fade-leave-active {
  /*
    note that we add absolute position to leaving element
    so other elements change their position and trigger move transition
  */
  position: absolute;
}

.fade-leave-from,
.fade-enter-to {
  transform: translateX(0);
  opacity: 1;
}

+.fade-move {
+  transition: transform 500ms ease;
+}

Custom move class

You could pass your move class if you don't want to use a generated one. Just pass a moveClass prop.

<Transition moveClass="my-move-class">
  {/* ... */}
</Transition>

Important note about move transition

When you use <TransitionGroup>, it assumes that you want to have a move transition. As a result, moveClass will be added to children, whenever they change their position. But if the styles for it don't have a transition, it won't get removed (unlike with the <Transition> component, which removes classes if the transition/animation is not defined). Because <TransitionGroup> doesn't check whether each child has transition or not, since it could be a performance bottleneck (for large lists). Therefore if you don't plan to have a move transition and don't want unnecessary classes on your elements - pass moveTransition={false}.

<TransitionGroup moveTransition={false}>
  {/* ... */}
</TransitionGroup>

Cool example

With <TransitionGroup/>'s move class you could make really cool animations. Checkout, for instance, this example:

Try in codesandbox

import React, { useState } from "react";
import { Transition, TransitionGroup } from "retransition";
import { shuffle } from "lodash-es";

import "./index.css";

const makeArr = () => {
  return Array(81)
    .fill(null)
    .map((_, index) => ({
      id: "quot; + index,
      number: (index % 9) + 1,
    }));
};

const App = () => {
  const [numbers, setNumbers] = useState(() => makeArr());

  return (
    <>
      <button onClick={() => setNumbers(v => shuffle(v))}>shuffle</button>{" "}
      <div className="container">
        <TransitionGroup name="cell">
          {numbers.map(({ id, number }) => (
            <Transition key={id}>
              <div className="cell">{number}</div>
            </Transition>
          ))}
        </TransitionGroup>
      </div>
    </>
  );
};
.container {
  display: flex;
  flex-wrap: wrap;
  width: 240px;
  margin-top: 10px;
}

.cell {
  display: flex;
  justify-content: space-around;
  align-items: center;
  width: 25px;
  height: 25px;
  border: 1px solid #aaa;
  margin-right: -1px;
  margin-bottom: -1px;
}

.cell:nth-child(3n) {
  margin-right: 0;
}

.cell:nth-child(27n) {
  margin-bottom: 0;
}

.cell-move {
  transition: transform 2s;
}

API

Transition

Props

name type default description
visible boolean false Determines wether to show component or nor, trigger transition on change
name string transition The name of the transition, used to generate a default transition classes
appear boolean false By default enter transition is not performed on initial render, if you want this behavior set appear and visible to true
customAppear boolean false By default appear transition uses enter classes and events. But if you want it to generate custom classes and not use enter events, pass true
nodeRef React.MutableRef<Element \| null> \| ((node: Element) => void undefined <Transition /> component passes ref to it's children. So if you also want to use ref pass it to the wrapping <Transition /> component
unmount boolean true By default the child is unmounted on exit. If you prefer no unmounting (hided with display: none) change this to false.
type 'animation' \| 'transition' \| undefined undefined Type of the transition that this component should care about
enterFromClass string `${name}-enter-from` Class that sets the starting styles of enter transition.
enterActiveClass string `${name}-enter-to` Class that sets the active style of enter transition. This class can be used to define the duration, delay and easing curve for the entering transition.
enterToClass string `${name}-enter-active` Class that sets the ending styles of enter transition.
leaveFromClass string `${name}-leave-from` Class that sets the starting styles of leave transition.
leaveActiveClass string `${name}-leave-active` Class that sets the active style of leave transition. This class can be used to define the duration, delay and easing curve for the leaving transition.
leaveToClass string `${name}-leave-to` Class that sets the ending styles of leave transition.
appearFromClass string `enterFromClass` Class that sets the starting styles of appear transition. By default enterFromClass is used. To change this behavior pass customAppear prop.
appearActiveClass string `enterActiveClass` Class that sets the active style of appear transition. This class can be used to define the duration, delay and easing curve for the appearing transition.
appearToClass string `enterToClass` Class that sets the ending styles of appear transition.
onBeforeEnter (el: Element) => void undefined JavaScript event. Called right before enterFromClass and enterActiveClass are added
onEnter (el: Element) => void undefined JavaScript event. Called after enterFromClass and enterActiveClass are added
onAfterEnter (el: Element) => void undefined JavaScript event. Called when enter transition is finished and all transition classes are removed
onBeforeLeave (el: Element) => void undefined JavaScript event. Called right before leaveFromClass and leaveActiveClass are added
onLeave (el: Element) => void undefined JavaScript event. Called after leaveFromClass and leaveActiveClass are added
onAfterLeave (el: Element) => void undefined JavaScript event. Called when leave transition is finished and all transition classes are removed
onBeforeAppear (el: Element) => void undefined JavaScript event. Called right before appearFromClass and appearActiveClass are added
onAppear (el: Element) => void undefined JavaScript event. Called after appearFromClass and appearActiveClass are added
onAfterAppear (el: Element) => void undefined JavaScript event. Called when appear transition is finished and all transition classes are removed

TransitionGroup

This is a container that wraps your <Transition> components and performs enter/leave transition on added/removed elements from the list.

Props

name type default description
name string transition Name for your child transitions, also used to generate moveClass if it's not provided.
moveClass string `${name}-move` Class that would be added to children that are moved due to element addition/removal.
appear boolean false if true performs appear transition for all of it's on initial render.
moveTransition boolean \| undefined undefined Determines whether <TransitionGroup> should have move transition.
children React.ReactElement - Elements wrapped in <Transition /> component.

Contributing

If you have any questions, suggestions, or improvements, feel free to open an issue or a pull request.

License

MIT.