View Transitions no React
Anime entre estados de UI usando a API nativa document.startViewTransition do navegador. Declare o que com <ViewTransition>, dispare quando com startTransition / useDeferredValue / Suspense, controle como com classes CSS. Navegadores sem suporte ignoram animações graciosamente.
Quando Animar
Cada <ViewTransition> deve comunicar uma relação espacial ou continuidade. Se você não consegue articular o que ela comunica, não a adicione.
Implemente todos os padrões aplicáveis desta lista, nesta ordem:
| Prioridade | Padrão | O que comunica |
|---|---|---|
| 1 | Elemento compartilhado (name) | "Mesma coisa, indo mais fundo" |
| 2 | Revelação de Suspense | "Dados carregados" |
| 3 | Identidade de lista (key por item) | "Mesmos itens, novo arranjo" |
| 4 | Mudança de estado (enter/exit) | "Algo apareceu/desapareceu" |
| 5 | Mudança de rota (nível de layout) | "Indo para um novo lugar" |
Esta é uma ordem de implementação, não uma lista de "escolha um". Implemente todo padrão que se encaixar no aplicativo. Só pule um padrão se o aplicativo não tiver caso de uso para ele.
Escolhendo o Estilo de Animação
| Contexto | Animação | Por quê |
|---|---|---|
| Navegação hierárquica (lista → detalhe) | nav-forward / nav-back com tipo | Comunica profundidade espacial |
| Navegação lateral (aba para aba) | <ViewTransition> simples (fade) ou default="none" | Sem profundidade a comunicar |
| Revelação de Suspense | Propriedades string enter/exit | Conteúdo chegando |
| Revalidação / atualização em segundo plano | default="none" | Silenciosa, sem animação necessária |
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 posição: "próximo" desliza da direita, "anterior" da esquerda. Navegação lateral/não ordenada (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 React canary internamente.ViewTransitionfunciona de imediato.npm ls reactpode mostrar uma versão aparentemente estável; isso é esperado. - Sem Next.js: Instale
react@canary react-dom@canary(ViewTransitionnão está no React estável). - Suporte de navegadores: Chromium 111+, Firefox 144+, Safari 18.2+. Degradação graciosa em navegadores sem suporte.
Fluxo de Trabalho de Implementação
Ao adicionar view transitions a um aplicativo existente, siga references/implementation.md passo a passo. Comece pela auditoria, não a pule. Copie as receitas CSS de references/css-recipes.md para a folha de estilos 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 único e chama document.startViewTransition nos bastidores. Nunca chame startViewTransition manualmente.
Gatilhos de Animação
| Gatilho | Quando dispara |
|---|---|
| enter | <ViewTransition> é inserido pela primeira vez durante uma Transição |
| exit | <ViewTransition> é removido pela primeira vez durante uma Transição |
| update | Mutações no DOM dentro de um <ViewTransition>. Com VTs aninhados, a mutação se aplica ao mais interno |
| share | Um VT nomeado desmonta e outro com o mesmo name monta na mesma Transição |
Apenas startTransition, useDeferredValue ou Suspense ativam VTs. setState comum não anima.
Regra Crítica de Posicionamento
<ViewTransition> só ativa enter/exit se aparecer antes de qualquer nó DOM:
// Funciona
<ViewTransition enter="auto" exit="auto">
<div>Conteúdo</div>
</ViewTransition>
// Quebrado: div envolve o VT, suprimindo enter/exit
<div>
<ViewTransition enter="auto" exit="auto">
<div>Conteúdo</div>
</ViewTransition>
</div>
Estilizando com Classes de View Transition
Props
Valores: "auto" (cross-fade do navegador), "none" (desabilitado), "nome-da-classe" (CSS personalizado), ou { [tipo]: valor } para animações específicas por tipo.
<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
Se default for "none", todos os gatilhos estão desligados a menos que explicitamente listados.
Pseudo-Elementos CSS
::view-transition-old(.class): snapshot de saída::view-transition-new(.class): snapshot de entrada::view-transition-group(.class): contêiner::view-transition-image-pair(.class): par antigo + novo
Veja references/css-recipes.md para receitas de animação prontas para uso.
Tipos de Transição
Marque transições com addTransitionType para que VTs possam escolher animações diferentes baseadas no contexto. Chame várias vezes para empilhar tipos; VTs diferentes na árvore reagem a tipos diferentes:
startTransition(() => {
addTransitionType('nav-forward');
addTransitionType('select-item');
router.push('/detail/1');
});
Passe um objeto para mapear tipos a classes CSS. Funciona em enter, exit e 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 e exit não precisam ser simétricos. Por exemplo, fade in mas slide out direcionalmente:
<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 exige uma chave default no objeto.
Para aplicativos com várias páginas, extraia o VT tipado em um wrapper reutilizável:
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() e Botão Voltar do Navegador
router.back() e os botões voltar/avançar do navegador não disparam view transitions (popstate é síncrono, incompatível com startViewTransition). Use router.push() com uma URL explícita.
Tipos e Suspense
Tipos estão disponíveis durante navegação, mas não durante revelações subsequentes de Suspense (transições separadas, sem tipo). Use mapas de tipo para enter/exit no nível da página; use props string simples para revelações de Suspense.
Transições de Elemento Compartilhado
Mesmo name em dois VTs, um desmontando e outro montando, cria uma transformação de elemento compartilhado:
<ViewTransition name="hero-image">
<img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>
// Na outra view, mesmo nome
<ViewTransition name="hero-image">
<img src="/full.jpg" />
</ViewTransition>
- Apenas um VT com um dado
namepode estar montado por vez. Use nomes únicos (photo-${id}). Cuidado com componentes reutilizáveis: se um componente com um VT nomeado é renderizado tanto em um modal/popover quanto em uma página, ambos montam simultaneamente e quebram a transformação. Torne o nome condicional (via prop) ou mova o VT nomeado para fora do componente compartilhado para o consumidor específico. sharetem precedência sobreenter/exit. Pense em cada caminho de navegação: quando nenhum par correspondente é formado (ex.: a página de destino não tem o mesmoname),enter/exitdispara em vez disso. Considere se o elemento precisa de uma animação de fallback para esses caminhos.- Nunca use uma saída fade-out em páginas com transformações compartilhadas. Use um slide direcional.
Padrões Comuns
Entrada/Saída
{show && (
<ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}
Reorganização de Lista
{items.map(item => (
<ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}
Dispara dentro de startTransition. Evite <div>s wrapper entre a lista e o VT.
Compondo Elementos Compartilhados com Identidade de Lista
Elementos compartilhados e identidade de lista são preocupações independentes, não confunda um com o outro. Quando um item de lista contém um elemento compartilhado (ex.: uma imagem que se transforma em uma view de detalhe), use dois limites <ViewTransition> aninhados:
{items.map(item => (
<ViewTransition key={item.id}> {/* identidade de lista */}
<Link href={`/items/${item.id}`}>
<ViewTransition name={`item-image-${item.id}`} share="morph"> {/* elemento compartilhado */}
<Image src={item.image} />
</ViewTransition>
<p>{item.name}</p>
</Link>
</ViewTransition>
))}
O VT externo lida com a reorganização de lista/entrada. O VT interno lida com a transformação de elemento compartilhado entre rotas. Faltar qualquer camada significa que essa animação silenciosamente não acontece.
Forçar Reentrada com key
<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
<ResultsGrid />
</ViewTransition>
Cuidado: Se envolver <Suspense>, mudar a key remonta o limite e refaz a busca.
Fallback de Suspense para Conteúdo
Cross-fade simples:
<ViewTransition>
<Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>
Revelação direcional:
<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
<ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>
Para mais padrões, veja references/patterns.md.
Como Múltiplos VTs Interagem
Todo VT que corresponde ao gatilho dispara simultaneamente em um único document.startViewTransition. VTs em diferentes transições (navegação vs resolução posterior de Suspense) não competem.
Use default="none" Generosamente
Sem ele, todo VT dispara o cross-fade do navegador em toda transição. Resolução de Suspense, atualizações de useDeferredValue, revalidações em segundo plano. Sempre use default="none" e habilite explicitamente apenas os gatilhos desejados.
Dois Padrões Coexistem
Padrão A. Slides direcionais: VT tipado em cada página, dispara durante navegação. Padrão B. Revelações de Suspense: Props string simples, dispara quando dados carregam (sem tipo).
Eles coexistem porque disparam em momentos diferentes. default="none" em ambos evita interferência cruzada. Sempre emparelhe enter com exit. Coloque VTs direcionais em componentes de página, não em layouts.
Limitação de VT Aninhado
Quando um VT pai sai, VTs aninhados dentro dele não disparam seus próprios enter/exit; apenas o VT mais externo anima. Animações escalonadas por item durante navegação de página não são possíveis atualmente. Veja react#36135 para uma correção experimental opcional.
Integração com Next.js
Para configuração do Next.js (flag experimental.viewTransition, prop transitionTypes em next/link, padrões do App Router, Server Components), veja references/nextjs.md.
Acessibilidade
Sempre adicione o CSS de movimento reduzido de references/css-recipes.md à sua folha de estilos global.
Arquivos de Referência
references/implementation.md: Fluxo de trabalho de implementação passo a passo.references/patterns.md: Padrões, temporização de animação, API de eventos, solução de problemas.references/css-recipes.md: Receitas de animação CSS prontas para uso.references/nextjs.md: Padrões do Next.js App Router e detalhes de Server Component.
Documento Completo Compilado
Para o guia completo com todos os arquivos de referência expandidos: AGENTS.md
