[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?