Transitions de Vue React
Animez entre les états d'interface en utilisant le document.startViewTransition natif du navigateur. Déclarez quoi avec <ViewTransition>, déclenchez quand avec startTransition / useDeferredValue / Suspense, contrôlez comment avec des classes CSS. Les navigateurs non pris en charge ignorent les animations avec élégance.
Quand Animer
Chaque <ViewTransition> doit communiquer une relation spatiale ou une continuité. Si vous ne pouvez pas articuler ce qu'il communique, ne l'ajoutez pas.
Implémentez tous les motifs applicables de cette liste, dans cet ordre :
| Priorité | Motif | Ce qu'il communique |
|---|---|---|
| 1 | Élément partagé (name) | "Même chose, plus en profondeur" |
| 2 | Révélation Suspense | "Données chargées" |
| 3 | Identité de liste (key par élément) | "Mêmes éléments, nouvel agencement" |
| 4 | Changement d'état (enter/exit) | "Quelque chose est apparu/disparu" |
| 5 | Changement de route (au niveau de la mise en page) | "Aller vers un nouvel endroit" |
C'est un ordre d'implémentation, pas une liste "choisissez-en un". Implémentez chaque motif qui correspond à l'application. Ne sautez un motif que si l'application n'a aucun cas d'usage pour celui-ci.
Choix du Style d'Animation
| Contexte | Animation | Pourquoi |
|---|---|---|
| Navigation hiérarchique (liste → détail) | Type-clé nav-forward / nav-back | Communique la profondeur spatiale |
| Navigation latérale (onglet à onglet) | <ViewTransition> simple (fondu) ou default="none" | Pas de profondeur à communiquer |
| Révélation Suspense | Props de chaîne enter/exit | Contenu arrivant |
| Revalidation / rafraîchissement en arrière-plan | default="none" | Silencieux, aucune animation nécessaire |
Réservez les glissements directionnels pour la navigation hiérarchique (liste → détail) et les séquences ordonnées (photo précédente/suivante, carrousel, résultats paginés). Pour les séquences ordonnées, la direction communique la position : "suivant" glisse depuis la droite, "précédent" depuis la gauche. La navigation latérale/non ordonnée (onglet à onglet) ne doit pas utiliser de glissements directionnels. Cela suggère faussement une profondeur spatiale.
Disponibilité
- Next.js : N'installez pas
react@canary: l'App Router inclut déjà React canary en interne.ViewTransitionfonctionne directement.npm ls reactpeut afficher une version stable ; c'est normal. - Sans Next.js : Installez
react@canary react-dom@canary(ViewTransitionn'est pas dans la version stable de React). - Support navigateur : Chromium 111+, Firefox 144+, Safari 18.2+. Dégradation élégante sur les navigateurs non pris en charge.
Flux de Travail d'Implémentation
Lors de l'ajout de transitions de vue à une application existante, suivez references/implementation.md étape par étape. Commencez par l'audit, ne le sautez pas. Copiez les recettes CSS de references/css-recipes.md dans la feuille de style globale, n'écrivez pas votre propre CSS d'animation.
Concepts Fondamentaux
Le Composant <ViewTransition>
import { ViewTransition } from 'react';
<ViewTransition>
<Component />
</ViewTransition>
React attribue automatiquement un view-transition-name unique et appelle document.startViewTransition en coulisses. N'appelez jamais startViewTransition vous-même.
Déclencheurs d'Animation
| Déclencheur | Quand il se déclenche |
|---|---|
| enter | <ViewTransition> inséré pour la première fois lors d'une Transition |
| exit | <ViewTransition> supprimé pour la première fois lors d'une Transition |
| update | Mutations DOM à l'intérieur d'un <ViewTransition>. Avec des VT imbriqués, la mutation s'applique au plus profond |
| share | VT nommé démonté et un autre avec le même name monté dans la même Transition |
Seuls startTransition, useDeferredValue, ou Suspense activent les VT. Les setState réguliers n'animent pas.
Règle de Placement Critique
<ViewTransition> n'active l'entrée/sortie que s'il apparaît avant tout nœud DOM :
// Fonctionne
<ViewTransition enter="auto" exit="auto">
<div>Contenu</div>
</ViewTransition>
// Cassé, div enveloppe le VT, supprimant l'entrée/sortie
<div>
<ViewTransition enter="auto" exit="auto">
<div>Contenu</div>
</ViewTransition>
</div>
Stylisation avec les Classes de Transition de Vue
Props
Valeurs : "auto" (fondu croisé du navigateur), "none" (désactivé), "nom-classe" (CSS personnalisé), ou { [type]: valeur } pour des animations spécifiques au type.
<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
Si default est "none", tous les déclencheurs sont désactivés sauf s'ils sont explicitement listés.
Pseudo-Éléments CSS
::view-transition-old(.class): instantané sortant::view-transition-new(.class): instantané entrant::view-transition-group(.class): conteneur::view-transition-image-pair(.class): paire ancien + nouveau
Voir references/css-recipes.md pour des recettes d'animation prêtes à l'emploi.
Types de Transition
Taguez les transitions avec addTransitionType afin que les VT puissent choisir différentes animations selon le contexte. Appelez-le plusieurs fois pour empiler les types, différents VT dans l'arbre réagissent à différents types :
startTransition(() => {
addTransitionType('nav-forward');
addTransitionType('select-item');
router.push('/detail/1');
});
Passez un objet pour mapper les types aux classes CSS. Fonctionne sur enter, exit, et 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 et exit n'ont pas à être symétriques. Par exemple, fondu à l'entrée mais glissement directionnel à la sortie :
<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 nécessite une clé default dans l'objet.
Pour les applications avec plusieurs pages, extrayez le VT typé-clé dans un wrapper réutilisable :
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() et le Bouton Retour du Navigateur
router.back() et les boutons retour/avant du navigateur ne déclenchent pas les transitions de vue (popstate est synchrone, incompatible avec startViewTransition). Utilisez plutôt router.push() avec une URL explicite.
Types et Suspense
Les types sont disponibles pendant la navigation mais pas pendant les révélations Suspense ultérieures (transitions séparées, pas de type). Utilisez les mappages de types pour les entrées/sorties au niveau de la page ; utilisez des props de chaîne simples pour les révélations Suspense.
Transitions d'Éléments Partagés
Même name sur deux VT, l'un se démontant, l'autre se montant, crée un morphing d'élément partagé :
<ViewTransition name="hero-image">
<img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>
// Sur l'autre vue, même nom
<ViewTransition name="hero-image">
<img src="/full.jpg" />
</ViewTransition>
- Un seul VT avec un
namedonné peut être monté à la fois. Utilisez des noms uniques (photo-${id}). Attention aux composants réutilisables : si un composant avec un VT nommé est rendu à la fois dans une modale/popover et une page, les deux se montent simultanément et cassent le morphing. Soit rendez le nom conditionnel (via une prop), soit déplacez le VT nommé hors du composant partagé vers le consommateur spécifique. sharea priorité surenter/exit. Réfléchissez à chaque chemin de navigation : lorsqu'aucune paire correspondante ne se forme (par exemple, la page cible n'a pas le même nom),enter/exitse déclenche à la place. Considérez si l'élément a besoin d'une animation de repli pour ces chemins.- N'utilisez jamais une sortie avec fondu disparaissant sur des pages avec des morphings partagés. Utilisez plutôt un glissement directionnel.
Motifs Courants
Entrée/Sortie
{show && (
<ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}
Réorganisation de Liste
{items.map(item => (
<ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}
Déclenchez à l'intérieur de startTransition. Évitez les <div> enveloppes entre la liste et le VT.
Composition d'Éléments Partagés avec Identité de Liste
Les éléments partagés et l'identité de liste sont des préoccupations indépendantes, ne confondez pas l'un pour l'autre. Lorsqu'un élément de liste contient un élément partagé (par exemple, une image qui se transforme en vue détaillée), utilisez deux limites <ViewTransition> imbriquées :
{items.map(item => (
<ViewTransition key={item.id}> {/* identité de liste */}
<Link href={`/items/${item.id}`}>
<ViewTransition name={`item-image-${item.id}`} share="morph"> {/* élément partagé */}
<Image src={item.image} />
</ViewTransition>
<p>{item.name}</p>
</Link>
</ViewTransition>
))}
Le VT externe gère la réorganisation de liste/les animations d'entrée. Le VT interne gère le morphing d'élément partagé inter-route. L'absence de l'une ou l'autre couche signifie que cette animation ne se produit pas silencieusement.
Forcer la Ré-entrée avec key
<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
<ResultsGrid />
</ViewTransition>
Prudence : Si vous enveloppez <Suspense>, changer key remonte la limite et relance le chargement.
Suspense du Fallback au Contenu
Fondu croisé simple :
<ViewTransition>
<Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>
Révélation directionnelle :
<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
<ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>
Pour plus de motifs, voir references/patterns.md.
Comment Plusieurs VT Interagissent
Chaque VT correspondant au déclencheur se déclenche simultanément dans un seul document.startViewTransition. Les VT dans des transitions différentes (navigation vs résolution Suspense ultérieure) ne sont pas en concurrence.
Utilisez default="none" Libéralement
Sans cela, chaque VT déclenche le fondu croisé du navigateur sur chaque transition. Résolution Suspense, mises à jour useDeferredValue, revalidations en arrière-plan. Utilisez toujours default="none" et activez explicitement uniquement les déclencheurs souhaités.
Deux Motifs Coexistent
Motif A. Glissements directionnels : VT typé-clé sur chaque page, se déclenche pendant la navigation. Motif B. Révélations Suspense : Props de chaîne simples, se déclenche lorsque les données sont chargées (pas de type).
Ils coexistent car ils se déclenchent à des moments différents. default="none" sur les deux empêche les interférences croisées. Associez toujours enter avec exit. Placez les VT directionnels dans les composants de page, pas dans les mises en page.
Limitation des VT Imbriqués
Lorsqu'un VT parent sort, les VT imbriqués à l'intérieur ne déclenchent pas leur propre entrée/sortie, seul le VT le plus externe anime. Les animations décalées par élément pendant la navigation de page ne sont pas possibles aujourd'hui. Voir react#36135 pour un correctif expérimental.
Intégration Next.js
Pour la configuration Next.js (drapeau experimental.viewTransition, prop transitionTypes sur next/link, motifs App Router, Server Components), voir references/nextjs.md.
Accessibilité
Ajoutez toujours le CSS de mouvement réduit de references/css-recipes.md à votre feuille de style globale.
Fichiers de Référence
references/implementation.md: Flux de travail d'implémentation étape par étape.references/patterns.md: Motifs, timing d'animation, API d'événements, dépannage.references/css-recipes.md: Recettes CSS d'animation prêtes à l'emploi.references/nextjs.md: Motifs de l'App Router Next.js et détails des Server Components.
Document Complet Compilé
Pour le guide complet avec tous les fichiers de référence développés : AGENTS.md
