React Transition Group Guide

React Transition Group manages component enter/exit transitions. Here's how to use it.

Installation#

npm install react-transition-group
npm install --save-dev @types/react-transition-group

CSSTransition#

import { CSSTransition } from 'react-transition-group';
import { useRef, useState } from 'react';

function FadeExample() {
  const [show, setShow] = useState(false);
  const nodeRef = useRef(null);

  return (
    <div>
      <button onClick={() => setShow(!show)}>Toggle</button>

      <CSSTransition
        in={show}
        timeout={300}
        classNames="fade"
        unmountOnExit
        nodeRef={nodeRef}
      >
        <div ref={nodeRef} className="box">
          Fading content
        </div>
      </CSSTransition>
    </div>
  );
}

// CSS
/*
.fade-enter {
  opacity: 0;
}

.fade-enter-active {
  opacity: 1;
  transition: opacity 300ms ease-in;
}

.fade-exit {
  opacity: 1;
}

.fade-exit-active {
  opacity: 0;
  transition: opacity 300ms ease-out;
}
*/

Transition States#

import { CSSTransition } from 'react-transition-group';

// All transition states
/*
  classNames="my"

  Entering:
  - my-enter         (initial enter state)
  - my-enter-active  (active enter state)
  - my-enter-done    (completed enter state)

  Exiting:
  - my-exit          (initial exit state)
  - my-exit-active   (active exit state)
  - my-exit-done     (completed exit state)
*/

function SlideExample() {
  const [show, setShow] = useState(false);
  const nodeRef = useRef(null);

  return (
    <CSSTransition
      in={show}
      timeout={500}
      classNames="slide"
      nodeRef={nodeRef}
    >
      <div ref={nodeRef} className="panel">
        Content
      </div>
    </CSSTransition>
  );
}

// CSS
/*
.slide-enter {
  transform: translateX(-100%);
}

.slide-enter-active {
  transform: translateX(0);
  transition: transform 500ms ease-out;
}

.slide-enter-done {
  transform: translateX(0);
}

.slide-exit {
  transform: translateX(0);
}

.slide-exit-active {
  transform: translateX(-100%);
  transition: transform 500ms ease-in;
}
*/

Custom Class Names#

import { CSSTransition } from 'react-transition-group';

function CustomClassesExample() {
  const [show, setShow] = useState(false);
  const nodeRef = useRef(null);

  return (
    <CSSTransition
      in={show}
      timeout={300}
      classNames={{
        enter: 'animate-enter',
        enterActive: 'animate-enter-active',
        enterDone: 'animate-visible',
        exit: 'animate-exit',
        exitActive: 'animate-exit-active',
        exitDone: 'animate-hidden',
      }}
      nodeRef={nodeRef}
    >
      <div ref={nodeRef}>Content</div>
    </CSSTransition>
  );
}

// Timeout object for different durations
function DifferentTimingsExample() {
  const [show, setShow] = useState(false);
  const nodeRef = useRef(null);

  return (
    <CSSTransition
      in={show}
      timeout={{
        enter: 500,
        exit: 300,
      }}
      classNames="slide"
      nodeRef={nodeRef}
    >
      <div ref={nodeRef}>Content</div>
    </CSSTransition>
  );
}

TransitionGroup#

import { TransitionGroup, CSSTransition } from 'react-transition-group';
import { useState, useRef } from 'react';

interface Item {
  id: number;
  text: string;
}

function ListExample() {
  const [items, setItems] = useState<Item[]>([
    { id: 1, text: 'Item 1' },
    { id: 2, text: 'Item 2' },
  ]);

  const addItem = () => {
    const newItem = {
      id: Date.now(),
      text: `Item ${items.length + 1}`,
    };
    setItems([...items, newItem]);
  };

  const removeItem = (id: number) => {
    setItems(items.filter(item => item.id !== id));
  };

  return (
    <div>
      <button onClick={addItem}>Add Item</button>

      <TransitionGroup component="ul" className="list">
        {items.map(item => (
          <CSSTransition
            key={item.id}
            timeout={300}
            classNames="item"
          >
            <li>
              {item.text}
              <button onClick={() => removeItem(item.id)}>×</button>
            </li>
          </CSSTransition>
        ))}
      </TransitionGroup>
    </div>
  );
}

// CSS
/*
.item-enter {
  opacity: 0;
  transform: translateY(-20px);
}

.item-enter-active {
  opacity: 1;
  transform: translateY(0);
  transition: all 300ms ease-out;
}

.item-exit {
  opacity: 1;
}

.item-exit-active {
  opacity: 0;
  transform: translateX(100%);
  transition: all 300ms ease-in;
}
*/

SwitchTransition#

import { SwitchTransition, CSSTransition } from 'react-transition-group';
import { useState, useRef } from 'react';

function TabSwitchExample() {
  const [activeTab, setActiveTab] = useState('home');
  const nodeRef = useRef(null);

  return (
    <div>
      <nav>
        <button onClick={() => setActiveTab('home')}>Home</button>
        <button onClick={() => setActiveTab('about')}>About</button>
        <button onClick={() => setActiveTab('contact')}>Contact</button>
      </nav>

      <SwitchTransition mode="out-in">
        <CSSTransition
          key={activeTab}
          timeout={200}
          classNames="fade"
          nodeRef={nodeRef}
        >
          <div ref={nodeRef} className="tab-content">
            {activeTab === 'home' && <HomeContent />}
            {activeTab === 'about' && <AboutContent />}
            {activeTab === 'contact' && <ContactContent />}
          </div>
        </CSSTransition>
      </SwitchTransition>
    </div>
  );
}

// Modes:
// "out-in": current exits, then new enters (sequential)
// "in-out": new enters, then current exits (overlapping)

// CSS
/*
.fade-enter {
  opacity: 0;
}

.fade-enter-active {
  opacity: 1;
  transition: opacity 200ms;
}

.fade-exit {
  opacity: 1;
}

.fade-exit-active {
  opacity: 0;
  transition: opacity 200ms;
}
*/

Transition Component#

import { Transition } from 'react-transition-group';
import { useRef } from 'react';

// For JavaScript-based animations
function TransitionExample() {
  const [show, setShow] = useState(false);
  const nodeRef = useRef(null);

  const duration = 300;

  const defaultStyle = {
    transition: `opacity ${duration}ms ease-in-out`,
    opacity: 0,
  };

  const transitionStyles = {
    entering: { opacity: 1 },
    entered: { opacity: 1 },
    exiting: { opacity: 0 },
    exited: { opacity: 0 },
  };

  return (
    <div>
      <button onClick={() => setShow(!show)}>Toggle</button>

      <Transition
        in={show}
        timeout={duration}
        nodeRef={nodeRef}
      >
        {state => (
          <div
            ref={nodeRef}
            style={{
              ...defaultStyle,
              ...transitionStyles[state],
            }}
          >
            Transitioning content
          </div>
        )}
      </Transition>
    </div>
  );
}

// With callbacks
function CallbacksExample() {
  const [show, setShow] = useState(false);
  const nodeRef = useRef(null);

  return (
    <Transition
      in={show}
      timeout={300}
      nodeRef={nodeRef}
      onEnter={() => console.log('Enter started')}
      onEntering={() => console.log('Entering')}
      onEntered={() => console.log('Entered')}
      onExit={() => console.log('Exit started')}
      onExiting={() => console.log('Exiting')}
      onExited={() => console.log('Exited')}
    >
      {state => <div ref={nodeRef}>State: {state}</div>}
    </Transition>
  );
}

import { CSSTransition } from 'react-transition-group';
import { useRef } from 'react';

function AnimatedModal({ isOpen, onClose, children }) {
  const overlayRef = useRef(null);
  const contentRef = useRef(null);

  return (
    <CSSTransition
      in={isOpen}
      timeout={300}
      classNames="modal-overlay"
      unmountOnExit
      nodeRef={overlayRef}
    >
      <div
        ref={overlayRef}
        className="modal-overlay"
        onClick={onClose}
      >
        <CSSTransition
          in={isOpen}
          timeout={300}
          classNames="modal-content"
          appear
          nodeRef={contentRef}
        >
          <div
            ref={contentRef}
            className="modal-content"
            onClick={e => e.stopPropagation()}
          >
            {children}
          </div>
        </CSSTransition>
      </div>
    </CSSTransition>
  );
}

// CSS
/*
.modal-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
}

.modal-overlay-enter {
  opacity: 0;
}

.modal-overlay-enter-active {
  opacity: 1;
  transition: opacity 300ms;
}

.modal-overlay-exit {
  opacity: 1;
}

.modal-overlay-exit-active {
  opacity: 0;
  transition: opacity 300ms;
}

.modal-content-enter,
.modal-content-appear {
  opacity: 0;
  transform: scale(0.9);
}

.modal-content-enter-active,
.modal-content-appear-active {
  opacity: 1;
  transform: scale(1);
  transition: all 300ms ease-out;
}

.modal-content-exit {
  opacity: 1;
  transform: scale(1);
}

.modal-content-exit-active {
  opacity: 0;
  transform: scale(0.9);
  transition: all 300ms ease-in;
}
*/

Route Transitions#

import { Routes, Route, useLocation } from 'react-router-dom';
import { TransitionGroup, CSSTransition } from 'react-transition-group';

function AnimatedRoutes() {
  const location = useLocation();

  return (
    <TransitionGroup component={null}>
      <CSSTransition
        key={location.pathname}
        timeout={300}
        classNames="page"
      >
        <Routes location={location}>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/contact" element={<Contact />} />
        </Routes>
      </CSSTransition>
    </TransitionGroup>
  );
}

// CSS
/*
.page-enter {
  opacity: 0;
  transform: translateX(100%);
}

.page-enter-active {
  opacity: 1;
  transform: translateX(0);
  transition: all 300ms ease-out;
}

.page-exit {
  opacity: 1;
  transform: translateX(0);
}

.page-exit-active {
  opacity: 0;
  transform: translateX(-100%);
  transition: all 300ms ease-in;
}
*/

Best Practices#

Usage:
✓ Use CSSTransition for CSS animations
✓ Use Transition for JS animations
✓ Use TransitionGroup for lists
✓ Use SwitchTransition for swapping

Performance:
✓ Use transform and opacity
✓ Add will-change cautiously
✓ Use unmountOnExit to clean up
✓ Match CSS and timeout values

Accessibility:
✓ Respect prefers-reduced-motion
✓ Keep animations brief
✓ Don't rely solely on animation
✓ Test with screen readers

Avoid:
✗ Animating layout properties
✗ Very long animations
✗ Animations on page load
✗ Too many simultaneous animations

React Transition Group provides low-level primitives for component transitions. Use CSSTransition for declarative CSS-based animations, Transition for JavaScript-controlled animations, and TransitionGroup for animating lists. Combine with SwitchTransition for smooth content switching.