Transições de Visualização no React

Anime entre estados da UI usando a funcionalidade nativa do navegador document.startViewTransition. Declare o quê com <ViewTransition>, acione quando com startTransition / useDeferredValue / Suspense, controle como com classes CSS. Navegadores sem suporte pulam animações de forma elegante.

Quando Usar

• Use esta habilidade quando a tarefa corresponder a esta descrição: Guiar transições de visualização no React e Next.js, animações de elementos compartilhados, transições de rota, tipos de transição e animação de estado de UI segura para movimento reduzido.

Quando Animar

Cada <ViewTransition> deve comunicar uma relação espacial ou continuidade. Se você não consegue articular o que ele comunica, não o adicione.

Implemente todos os padrões aplicáveis desta lista, nesta ordem:

Esta é uma ordem de implementação, não uma lista de "escolha um". Implemente todos os padrões que se encaixam no aplicativo. Pule um padrão apenas se o aplicativo não tiver um caso de uso para ele.

Escolhendo o Estilo de Animação

Reserve slides direcionais para navegação hierárquica (lista → detalhe) e sequências ordenadas (foto anterior/próxima, carrossel, resultados paginados). Para sequências ordenadas, a direção comunica a posição: "próximo" desliza da direita, "anterior" da esquerda. Navegação lateral/desordenada (aba para aba) não deve usar slides direcionais — isso implica falsamente profundidade espacial.

Disponibilidade

• Next.js: Não instale react@canary — o App Router já inclui o React canary internamente. ViewTransition funciona de imediato. npm ls react pode mostrar uma versão com aparência estável; isso é esperado.
• Sem Next.js: Instale react@canary react-dom@canary (ViewTransition não está no React estável).
• Suporte do navegador: Chromium 111+, Firefox 144+, Safari 18.2+. Degradação elegante em navegadores sem suporte.

Fluxo de Implementação

Ao adicionar transições de visualização a um aplicativo existente, siga references/implementation.md passo a passo. Comece com a auditoria — não a pule. Copie as receitas CSS de references/css-recipes.md para a folha de estilo global — não escreva seu próprio CSS de animação.

Conceitos Principais

O Componente <ViewTransition>

import { ViewTransition } from 'react';

<ViewTransition>
  <Component />
</ViewTransition>

O React atribui automaticamente um view-transition-name exclusivo e chama document.startViewTransition nos bastidores. Nunca chame startViewTransition você mesmo.

Gatilhos de Animação

Apenas startTransition, useDeferredValue ou Suspense ativam VTs. setState regular não anima.

Regra de Posicionamento Crítico

<ViewTransition> ativa enter/exit apenas se aparecer antes de quaisquer nós DOM:

// Works
<ViewTransition enter="auto" exit="auto">
  <div>Content</div>
</ViewTransition>

// Broken — div wraps the VT, suppressing enter/exit
<div>
  <ViewTransition enter="auto" exit="auto">
    <div>Content</div>
  </ViewTransition>
</div>

Estilizando com Classes de Transição de Visualização

Props

Valores: "auto" (cross-fade do navegador), "none" (desativado), "class-name" (CSS personalizado), ou { [type]: value } para animações específicas do tipo.

<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />

…