Transiciones de Vista en React
Anima entre estados de la interfaz usando la API nativa del navegador document.startViewTransition. Declara qué con <ViewTransition>, activa cuándo con startTransition / useDeferredValue / Suspense, controla cómo con clases CSS. Los navegadores no compatibles omiten las animaciones elegantemente.
Cuándo Animar
Cada <ViewTransition> debe comunicar una relación espacial o continuidad. Si no puedes articular qué comunica, no lo añadas.
Implementa todos los patrones aplicables de esta lista, en este orden:
| Prioridad | Patrón | Qué comunica |
|---|---|---|
| 1 | Elemento compartido (name) | "Lo mismo, yendo más profundo" |
| 2 | Revelación de Suspense | "Datos cargados" |
| 3 | Identidad de lista (key por elemento) | "Mismos elementos, nueva disposición" |
| 4 | Cambio de estado (enter/exit) | "Algo apareció/desapareció" |
| 5 | Cambio de ruta (a nivel de layout) | "Yendo a un nuevo lugar" |
Este es un orden de implementación, no una lista de "elige uno". Implementa cada patrón que se ajuste a la aplicación. Solo omite un patrón si la aplicación no tiene caso de uso para él.
Elegir el Estilo de Animación
| Contexto | Animación | Por qué |
|---|---|---|
| Navegación jerárquica (lista → detalle) | Tipo-clave nav-forward / nav-back | Comunica profundidad espacial |
| Navegación lateral (pestaña a pestaña) | <ViewTransition> simple (fundido) o default="none" | Sin profundidad que comunicar |
| Revelación de Suspense | Props de cadena enter/exit | Contenido que llega |
| Revalidación / actualización en segundo plano | default="none" | Silencioso, sin animación necesaria |
Reserva los deslizamientos direccionales para navegación jerárquica (lista → detalle) y secuencias ordenadas (foto anterior/siguiente, carrusel, resultados paginados). Para secuencias ordenadas, la dirección comunica la posición: "siguiente" desliza desde la derecha, "anterior" desde la izquierda. La navegación lateral/desordenada (pestaña a pestaña) no debe usar deslizamientos direccionales. Falsamente implica profundidad espacial.
Disponibilidad
- Next.js: No instales
react@canary: el App Router ya incluye React canary internamente.ViewTransitionfunciona directamente.npm ls reactpuede mostrar una versión de apariencia estable; esto es esperado. - Sin Next.js: Instala
react@canary react-dom@canary(ViewTransitionno está en React estable). - Soporte de navegadores: Chromium 111+, Firefox 144+, Safari 18.2+. Degradación elegante en navegadores no compatibles.
Flujo de Trabajo de Implementación
Al añadir view transitions a una aplicación existente, sigue references/implementation.md paso a paso. Comienza con la auditoría, no la omitas. Copia las recetas CSS de references/css-recipes.md en la hoja de estilos global, no escribas tu propio CSS de animación.
Conceptos Clave
El Componente <ViewTransition>
import { ViewTransition } from 'react';
<ViewTransition>
<Component />
</ViewTransition>
React asigna automáticamente un view-transition-name único y llama a document.startViewTransition internamente. Nunca llames a startViewTransition tú mismo.
Disparadores de Animación
| Disparador | Cuándo se activa |
|---|---|
| enter | El <ViewTransition> se inserta por primera vez durante una Transición |
| exit | El <ViewTransition> se elimina por primera vez durante una Transición |
| update | Mutaciones del DOM dentro de un <ViewTransition>. Con VTs anidados, la mutación se aplica al más interno |
| share | Un VT nombrado se desmonta y otro con el mismo name se monta en la misma Transición |
Solo startTransition, useDeferredValue o Suspense activan los VTs. Un setState regular no anima.
Regla Crítica de Colocación
<ViewTransition> solo activa enter/exit si aparece antes de cualquier nodo del DOM:
// Funciona
<ViewTransition enter="auto" exit="auto">
<div>Contenido</div>
</ViewTransition>
// Roto, el div envuelve al VT, suprimiendo enter/exit
<div>
<ViewTransition enter="auto" exit="auto">
<div>Contenido</div>
</ViewTransition>
</div>
Estilizado con Clases de View Transition
Props
Valores: "auto" (fundido cruzado del navegador), "none" (desactivado), "nombre-clase" (CSS personalizado), o { [tipo]: valor } para animaciones específicas por tipo.
<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
Si default es "none", todos los disparadores están desactivados a menos que se listen explícitamente.
Pseudo-Elementos CSS
::view-transition-old(.clase): instantánea saliente::view-transition-new(.clase): instantánea entrante::view-transition-group(.clase): contenedor::view-transition-image-pair(.clase): par antiguo + nuevo
Consulta references/css-recipes.md para recetas de animación listas para usar.
Tipos de Transición
Etiqueta las transiciones con addTransitionType para que los VTs puedan elegir diferentes animaciones según el contexto. Llámalo varias veces para apilar tipos; diferentes VTs en el árbol reaccionan a diferentes tipos:
startTransition(() => {
addTransitionType('nav-forward');
addTransitionType('select-item');
router.push('/detail/1');
});
Pasa un objeto para mapear tipos a clases CSS. Funciona en enter, exit y share:
<ViewTransition
enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
default="none"
>
<Page />
</ViewTransition>
enter y exit no tienen por qué ser simétricos. Por ejemplo, fundido al entrar pero deslizamiento direccional al salir:
<ViewTransition
enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
default="none"
>
TypeScript: ViewTransitionClassPerType requiere una clave default en el objeto.
Para aplicaciones con múltiples páginas, extrae el VT con clave de tipo en un envoltorio reutilizable:
export function DirectionalTransition({ children }: { children: React.ReactNode }) {
return (
<ViewTransition
enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
default="none"
>
{children}
</ViewTransition>
);
}
router.back() y Botón de Atrás del Navegador
router.back() y los botones de atrás/adelante del navegador no activan view transitions (popstate es síncrono, incompatible con startViewTransition). Usa router.push() con una URL explícita en su lugar.
Tipos y Suspense
Los tipos están disponibles durante la navegación pero no durante revelaciones posteriores de Suspense (transiciones separadas, sin tipo). Usa mapas de tipos para enter/exit a nivel de página; usa props de cadena simples para revelaciones de Suspense.
Transiciones de Elementos Compartidos
El mismo name en dos VTs, uno desmontándose y otro montándose, crea una transformación de elemento compartido:
<ViewTransition name="hero-image">
<img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>
// En la otra vista, mismo nombre
<ViewTransition name="hero-image">
<img src="/full.jpg" />
</ViewTransition>
- Solo un VT con un
namedado puede estar montado a la vez. Usa nombres únicos (photo-${id}). Cuidado con componentes reutilizables: si un componente con un VT nombrado se renderiza tanto en un modal/popover como en una página, ambos se montan simultáneamente y rompen la transformación. Haz que el nombre sea condicional (mediante una prop) o mueve el VT nombrado fuera del componente compartido al consumidor específico. sharetiene prioridad sobreenter/exit. Piensa en cada ruta de navegación: cuando no se forma un par coincidente (por ejemplo, la página de destino no tiene el mismo nombre), se activaenter/exiten su lugar. Considera si el elemento necesita una animación de respaldo para esas rutas.- Nunca uses una salida con fundido de desaparición en páginas con transformaciones compartidas. Usa un deslizamiento direccional en su lugar.
Patrones Comunes
Entrar/Salir
{show && (
<ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}
Reordenación de Lista
{items.map(item => (
<ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}
Actívalo dentro de startTransition. Evita <div>s envoltorios entre la lista y el VT.
Componer Elementos Compartidos con Identidad de Lista
Los elementos compartidos y la identidad de lista son preocupaciones independientes, no confundas uno con el otro. Cuando un elemento de lista contiene un elemento compartido (por ejemplo, una imagen que se transforma en una vista de detalle), usa dos límites <ViewTransition> anidados:
{items.map(item => (
<ViewTransition key={item.id}> {/* identidad de lista */}
<Link href={`/items/${item.id}`}>
<ViewTransition name={`item-image-${item.id}`} share="morph"> {/* elemento compartido */}
<Image src={item.image} />
</ViewTransition>
<p>{item.name}</p>
</Link>
</ViewTransition>
))}
El VT exterior maneja la reordenación de lista/animaciones de entrada. El VT interior maneja la transformación del elemento compartido entre rutas. Si falta cualquiera de las capas, esa animación simplemente no ocurre.
Forzar Re-Entrada con key
<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
<ResultsGrid />
</ViewTransition>
Precaución: Si envuelve <Suspense>, cambiar key vuelve a montar el límite y vuelve a obtener datos.
De Fallback de Suspense a Contenido
Fundido cruzado simple:
<ViewTransition>
<Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>
Revelación direccional:
<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
<ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>
Para más patrones, consulta references/patterns.md.
Cómo Interactúan Múltiples VTs
Cada VT que coincida con el disparador se activa simultáneamente en un solo document.startViewTransition. Los VTs en diferentes transiciones (navegación vs resolución posterior de Suspense) no compiten.
Usa default="none" Liberalmente
Sin él, cada VT activa el fundido cruzado del navegador en cada transición. Resoluciones de Suspense, actualizaciones de useDeferredValue, revalidaciones en segundo plano. Siempre usa default="none" y habilita explícitamente solo los disparadores deseados.
Dos Patrones Coexisten
Patrón A. Deslizamientos direccionales: VT con clave de tipo en cada página, se activa durante la navegación. Patrón B. Revelaciones de Suspense: Props de cadena simples, se activan cuando los datos cargan (sin tipo).
Coexisten porque se activan en momentos diferentes. default="none" en ambos evita la interferencia cruzada. Siempre empareja enter con exit. Coloca los VTs direccionales en componentes de página, no en layouts.
Limitación de VTs Anidados
Cuando un VT padre sale, los VTs anidados dentro de él no activan su propio enter/exit, solo el VT más externo anima. Las animaciones escalonadas por elemento durante la navegación de página no son posibles hoy. Consulta react#36135 para una corrección experimental opt-in.
Integración con Next.js
Para la configuración de Next.js (bandera experimental.viewTransition, prop transitionTypes en next/link, patrones del App Router, Componentes de Servidor), consulta references/nextjs.md.
Accesibilidad
Siempre añade el CSS de movimiento reducido de references/css-recipes.md a tu hoja de estilos global.
Archivos de Referencia
references/implementation.md: Flujo de trabajo de implementación paso a paso.references/patterns.md: Patrones, sincronización de animaciones, API de eventos, solución de problemas.references/css-recipes.md: Recetas CSS de animación listas para usar.references/nextjs.md: Patrones del App Router de Next.js y detalles de Componentes de Servidor.
Documento Completo Compilado
Para la guía completa con todos los archivos de referencia expandidos: AGENTS.md
