Ajoutez facilement des transitions animées entre les pages en utilisant Next.js App Router et votre bibliothèque d'animation préférée.

• Démo en direct utilisant GSAP (code source : /example).
• Démo Stackblitz utilisant Framer Motion.

Fonctionnalités

• Détection automatique des liens internes pour gérer les transitions de page (option auto).
• Utilisez un composant Link personnalisé pour gérer manuellement les transitions de page (quand auto est désactivé).
• Exclusivement destiné à être utilisé avec Next.js App Router (v14.0.0 ou supérieur).
• Ajoutez rapidement des transitions animées entre les pages avec JavaScript ou CSS.
• Intégration transparente avec GSAP ou toute autre bibliothèque d'animation de votre choix (voir exemple minimal avec GSAP).
• Si JavaScript est désactivé, l'accessibilité du routeur n'est pas compromise.
• Très léger ; la taille du bundle est inférieure à 8 Ko.
• Axé sur des animations personnalisables, sans viser l'API View Transitions.

Si vous souhaitez utiliser l’API View Transitions, consultez next-view-transitions.

[!WARNING]

Ce projet est actuellement en version Beta. Veuillez noter que l’API peut évoluer au fur et à mesure des améliorations et affinements des fonctionnalités.

Installation

Installez le package avec votre gestionnaire de paquets préféré :

pnpm add next-transition-router

yarn add next-transition-router

npm install next-transition-router

bun add next-transition-router

Utilisation

TransitionRouter

Créez un composant client (par exemple : app/providers.tsx) pour utiliser le fournisseur TransitionRouter :

"use client";
import { TransitionRouter } from "next-transition-router";
export function Providers({ children }: { children: React.ReactNode }) {
  return (
     {
        someAnimation().then(next);
      }}
      enter={(next) => {
        anotherAnimation().then(next);
      }}
    >
      {children}
    
  );
}

[!NOTE]

Il doit s'agir d'un composant client car vous devez passer des fonctions DOM en tant que props au provider.

Après cela, vous devez importer ce composant dans le composant de mise en page (par exemple : app/layout.tsx).

#### Rappels asynchrones

Les rappels leave et enter prennent en charge les fonctions asynchrones.

"use client";
import { TransitionRouter } from "next-transition-router";
export function Providers({ children }: { children: React.ReactNode }) {
  return (
     {
        await someAsyncAnimation();
        next();
      }}
      enter={async (next) => {
        await anotherAsyncAnimation();
        next();
      }}
    >
      {children}
    
  );
}

#### Paramètres from et to pour le rappel leave

Le rappel leave reçoit les paramètres from et to, qui sont des chaînes avec les chemins de la page précédente et suivante. Utile si vous souhaitez animer la transition de manière conditionnelle en fonction de la page.

const onLeave = (next, from, to) => {
  someAnimation(from, to).then(next);
};

[!NOTE]

Lors de l'utilisation de la méthode router.back(), le paramètre to sera indéfini. Voir navigation programmatique.

Gestion des liens (composant Link personnalisé vs détection automatique)

Pour déterminer comment gérer les liens, TransitionRouter peut recevoir une prop auto (boolean).

#### auto désactivé (par défaut)

Utilisez le composant Link personnalisé au lieu du composant natif Link de Next.js pour déclencher les transitions.

import { Link } from "next-transition-router";
export function Example() {
  return About;
}

[!ASTUCE]

Utilisez import { Link as TransitionLink } from "next-transition-router" pour éviter les conflits de noms.

#### auto activé

Lorsque auto est activé, le TransitionRouter intercepte les clics sur les liens internes, sauf les liens d’ancrage, et déclenche les transitions de page. Dans ce cas, vous n’avez pas besoin d’utiliser le composant Link personnalisé.

Pour ignorer un lien dans ce mode, ajoutez simplement l’attribut data-transition-ignore au lien.

Navigation programmatique

Utilisez le hook useTransitionRouter pour gérer la navigation (push, replace, back).

C’est similaire à Next.js useRouter avec un support de transition ajouté.

"use client";
import { useTransitionRouter } from "next-transition-router";
export function Programmatic() {
  const router = useTransitionRouter();
  return (
     {
        alert("Do something before navigating away");
        router.push("/about");
      }}
    >
      Go to /about
    
  );
}

[!IMPORTANT]

La navigation arrière et avant du navigateur ne déclenche pas les transitions de page, et c'est intentionnel.

État de la transition

Utilisez le hook useTransitionState pour déterminer l’étape actuelle de la transition.

Valeurs possibles de stage : 'entering' | 'leaving' | 'none'.

De plus, vous avez l’état isReady (boolean).

"use client";
import { useTransitionState } from "next-transition-router";
export function Example() {
  const { stage, isReady } = useTransitionState();
  return (
    

      
Current stage: {stage}
      
Page ready: {isReady ? "Yes" : "No"}
    
  );
}

[!CONSEIL]

Cela est utile, par exemple, si vous souhaitez déclencher une animation de révélation après la fin de la transition de page.

Nettoyage

TransitionRouter gère les fonctions de nettoyage pour les rappels leave et enter, afin de prévenir les fuites de mémoire.

Similaire au hook useEffect de React, vous pouvez retourner une fonction de nettoyage pour annuler l’animation.

#### Exemple minimal utilisant GSAP

"use client";
import { gsap } from "gsap";
import { TransitionRouter } from "next-transition-router";
export function Providers({ children }: { children: React.ReactNode }) {
  return (
     {
        const tween = gsap.fromTo("main", { autoAlpha: 1 }, { autoAlpha: 0, onComplete: next });
        return () => tween.kill();
      }}
      enter={(next) => {
        const tween = gsap.fromTo("main", { autoAlpha: 0 }, { autoAlpha: 1, onComplete: next });
        return () => tween.kill();
      }}
    >
      {children}
    
  );
}

Optimisation des performances

Lors du chevauchement des animations de sortie avec le chargement de la page (courant pour des transitions fluides), le rendu React peut provoquer des saccades d'animation. Utilisez requestAnimationFrame et startTransition pour prioriser les performances d'animation :

import { startTransition } from "react";
enter={(next) => {
  const tl = gsap.timeline()
    .to(".overlay", { y: "-100%", duration: 0.5 })
    .call(() => {
      requestAnimationFrame(() => startTransition(next));
    }, undefined, "<50%"); // Overlap timing preserved
    
  return () => tl.kill();
}}

Cela empêche les mises à jour React d'interférer avec votre chronologie d'animation tout en maintenant le timing visuel.

API

TransitionRouter

| Prop | Type | Valeur par défaut | Description | | ---------- | ---------- | ----------------- | ------------------------------------------------- | | leave | function | next => next() | Fonction pour gérer l'animation de sortie | | enter | function | next => next() | Fonction pour gérer l'animation d'entrée | | auto | boolean | false | Indicateur pour activer/désactiver la détection automatique des liens |

useTransitionState

| Propriété | Type | Description | |-----------|------------------------------------|----------------------------------------------------| | stage | 'entering' \| 'leaving' \| 'none' | Indique l'étape actuelle de la transition. | | isReady | boolean | Indique si la nouvelle page est prête à être animée. |

Avertissement

Ce paquet peut ne pas couvrir tous les cas d'utilisation. Si vous avez un scénario spécifique, veuillez ouvrir un ticket, et nous pourrons étudier la possibilité d'étendre la fonctionnalité.

Licence

MIT.

--- Tranlated By Open Ai Tx | Last indexed: 2026-06-07 ---