Document : méthode startViewTransition()

Baseline 2025 *

Newly available

Depuis October 2025, cette fonctionnalité fonctionne sur les appareils et les versions de navigateur les plus récents. Elle peut ne pas fonctionner sur les appareils ou navigateurs plus anciens.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

La méthode startViewTransition() de l'interface Document démarre une nouvelle transition de vue dans le même document (SPA) et retourne un objet ViewTransition pour la représenter.

Lorsque startViewTransition() est invoqué, une séquence d'étapes est suivie comme expliqué dans Le processus de transition de vue.

Une fonction de rappel optionnelle généralement appelée pour mettre à jour le DOM pendant le processus de transition de vue sur des applications monopages (SPA, pour Single Page Application en anglais), qui retourne une promesse (Promise). La fonction de rappel est appelée une fois que l'API a pris un instantané de la page actuelle. Lorsque la promesse retournée par la fonction de rappel est résolue, la transition de vue commence dans l'image suivante. Si la promesse retournée par la fonction de rappel est rejetée, la transition est abandonnée.

options Facultatif

Un objet contenant des options pour configurer la transition de vue. Il peut inclure les propriétés suivantes :

update Facultatif: La même fonction updateCallback décrite ci-dessus. Par défaut : null.
types Facultatif: Un tableau de chaînes de caractères représentant les types appliqués à la transition de vue. Types de transition de vue permettent l'application sélective de styles CSS ou de logique JavaScript selon le type de transition en cours. Par défaut, une séquence vide.

Valeur de retour

Une instance d'objet ViewTransition.

Exemples

Voir l'API de transition de vue > exemples pour une liste complète d'exemples.

Utilisation simple

Dans cette transition de vue sur le même document, nous vérifions si le navigateur prend en charge les transitions de vue. Si ce n'est pas le cas, nous définissons la couleur d'arrière-plan à l'aide d'une méthode de secours appliquée immédiatement. Sinon, nous pouvons appeler document.startViewTransition() avec des règles d'animation définies en CSS.

html

<main>
  <section></section>
  <button id="change-color">Changer la couleur</button>
</main>

Nous définissons la propriété animation-duration à 2 secondes en utilisant le pseudo-élément CSS ::view-transition-group.

css

html {
  --bg: indigo;
}
main {
  display: flex;
  flex-direction: column;
  gap: 5px;
}
section {
  background-color: var(--bg);
  height: 60px;
  border-radius: 5px;
}
::view-transition-group(root) {
  animation-duration: 2s;
}

const colors = ["darkred", "darkslateblue", "darkgreen"];
const colBlock = document.querySelector("section");
let count = 0;
const updateColor = () => {
  colBlock.style = `--bg: ${colors[count]}`;
  count = count !== colors.length - 1 ? ++count : 0;
};
const changeColor = () => {
  // Méthode de secours pour les navigateurs qui ne prennent pas en charge les transitions de vue :
  if (!document.startViewTransition) {
    updateColor();
    return;
  }

  // Avec les transitions de vue :
  const transition = document.startViewTransition(() => {
    updateColor();
  });
};
const changeColorButton = document.querySelector("#change-color");
changeColorButton.addEventListener("click", changeColor);
changeColorButton.addEventListener("keypress", changeColor);

Si les transitions de vue sont prises en charge, cliquer sur le bouton fera passer la couleur d'une à une autre sur 2 secondes. Sinon, la couleur d'arrière-plan est définie à l'aide d'une méthode de secours, sans animation.