[RFC] Add useDomTransition hook for better DX in DOM animations

[Moon-DaeSeung]

[RFC] Add useDomTransition hook for better DX in DOM animations

Summary

Propose a built-in useDomTransition hook that leverages React 19's new useRef cleanup functionality to provide declarative DOM animations without requiring external libraries.

Motivation

Current Pain Points in React DOM Animations

1. Library Dependency Hell
Currently, developers need heavy libraries for basic DOM transitions:

• React Transition Group (47.8kB)
• Framer Motion (175kB)
• React Spring (89kB)

2. Complex State Management
Without libraries, developers resort to complex patterns:

const [isVisible, setIsVisible] = useState(true);
const [shouldRender, setShouldRender] = useState(true);

const handleExit = () => {
  setIsVisible(false);
  setTimeout(() => setShouldRender(false), 300);
};

3. Competitive Disadvantage
Svelte provides built-in animation directives (in:, out:, transition:), offering superior DX out of the box. React developers deserve the same level of built-in animation support.

Detailed Design

Usage Example

const transition = useDomTransition();

return (

setShow(!show)}>Toggle

{show && (
<div ref={transition({
in: (element) => ({
duration: 300,
tick: (progress) => {
element.style.opacity = progress.toString();
}
}),
out: (element) => ({
duration: 300,
tick: (progress) => {
element.style.opacity = progress.toString();
}
})
})}>
Hello World! 👋

)}

);

Implementation

"use client";

import { useRef, useCallback } from "react";
import { linear } from "../easing";

export interface TransitionConfig {
duration?: number;
easing?: (t: number) => number;
tick?: (t: number) => void;
}

export interface TransitionOptions {
in: (node: HTMLElement) => TransitionConfig | Promise;
out: (node: HTMLElement) => TransitionConfig | Promise;
}

// Enhanced useDomTransition - allows inline option specification
export const useDomTransition = () => {
const containerRef = useRef<HTMLElement | null>(null);
const optionsRef = useRef<TransitionOptions | null>(null);
const elementRef = useRef<HTMLElement | null>(null);
const originalNextSiblingRef = useRef<Element | null>(null);

const stableCallback = useCallback((element: HTMLElement | null) => {
if (!element || !optionsRef.current) return;
elementRef.current = element;

const { in: inConfig, out: outConfig } = optionsRef.current;

// Store parent element and next sibling for order preservation
containerRef.current = element.parentElement;
originalNextSiblingRef.current = element.nextElementSibling;

// Handle in transition configuration (with Promise support)
const handleInTransition = async () => {
  const inOptions = await Promise.resolve(inConfig(elementRef.current!));
  const {
    duration: inDuration = 300,
    tick: inTick,
    easing: inEasing = linear,
  } = inOptions;

  // Execute animation
  if (inTick) {
    const startTime = performance.now();

    const animate = () => {
      const elapsed = performance.now() - startTime;
      const progress = Math.min(elapsed / inDuration, 1);
      const t = inEasing(progress);

      inTick(t);

      if (progress < 1) {
        requestAnimationFrame(animate);
      }
    };

    requestAnimationFrame(animate);
  }
};

handleInTransition();

// Cleanup function (when element unmounts)
return () => {
  if (!containerRef.current || !elementRef.current) return;

  // Create element clone
  const clone = elementRef.current.cloneNode(true) as HTMLElement;

  // Handle out transition configuration (with Promise support)
  const handleOutTransition = async () => {
    const outOptions = await Promise.resolve(outConfig(clone));
    const {
      duration: outDuration = 300,
      tick: outTick,
      easing: outEasing = linear,
    } = outOptions;

    // Insert clone at original position (order preservation)
    if (containerRef.current) {
      if (originalNextSiblingRef.current && containerRef.current.contains(originalNextSiblingRef.current)) {
        // Insert before original next sibling if it still exists
        containerRef.current.insertBefore(clone, originalNextSiblingRef.current);
      } else {
        // Append at the end if next sibling doesn't exist or was removed
        containerRef.current.appendChild(clone);
      }
    }
   
    // Execute animation
    if (outTick) {
      const startTime = performance.now();

      const animate = () => {
        const elapsed = performance.now() - startTime;
        const progress = Math.min(elapsed / outDuration, 1);
        const t = outEasing(1 - progress); // out goes from 1 to 0

        outTick(t);

        if (progress < 1) {
          requestAnimationFrame(animate);
        } else {
          clone.remove();
        }
      };

      requestAnimationFrame(animate);
    } else {
      // Remove after duration if no tick function
      setTimeout(() => {
        clone.remove();
      }, outDuration);
    }
  };

  handleOutTransition();
};

}, []);

// Function that receives options and returns ref callback
return (options: TransitionOptions) => {
optionsRef.current = options;
return stableCallback;
};
};

How it Works

The hook leverages React 19's new useRef cleanup capability:

1. Mount Phase: When element mounts, execute in transition
2. Unmount Phase: When element unmounts, useRef cleanup creates a clone and runs out transition
3. Cleanup: Remove cloned element after animation completes

This approach eliminates the need for complex state management while providing smooth enter/exit animations.

Benefits

Developer Experience

• Zero Dependencies: No need for animation libraries for basic transitions
• Declarative API: Clean, React-like animation declarations
• Type Safety: Full TypeScript support out of the box
• Small API Surface: Single hook handles all common animation needs

Performance

• Bundle Size: Reduces bundle size by eliminating animation library dependencies
• Runtime: Leverages native requestAnimationFrame and CSS transitions
• Memory: Efficient cleanup prevents memory leaks

Ecosystem Impact

• Learning Curve: New React developers get animations without learning external APIs
• Consistency: Standardized animation patterns across React apps

[jeremy-deutsch]

Does the <ViewTransition> component satisfy this use case?

[salemmohdmohd]

yes

[marstrx]

yes its will be a great idea

[SaurabhCodesAI]

This is an elegant shift not just a new hook, but a cleaner mental model for lifecycle aware DOM transitions.
It solves a real gap animation logic that’s declarative, localized, and React native without bloated abstractions.
Feels like what ReactTransitionGroup should have been but scoped, modern and inline with React 19's design.
Strong case for this as an experimental package. I’d use this today.

[shahdinsalman23]

The proposed useDomTransition hook would help streamline DOM animation handling in React by:

Providing a declarative API for triggering animations without manually juggling useEffect and refs.

Managing state-to-DOM synchronization, so animations run exactly when elements enter, update, or leave.

Handling cleanup and cancellation automatically, preventing memory leaks or orphaned animations.

Improving developer experience (DX) by reducing boilerplate and making animations easier to read and maintain.

In practice, it could wrap around the Web Animations API or CSS transitions, exposing a simple React-friendly interface.
This would make animations more predictable in concurrent rendering scenarios and avoid issues with manual DOM manipulation.