Getting started General
Components
Forms
Trends
Utilities
Migrate from v1
  Join us
  Vue Articles

Vue nextTick() : à quoi ça sert et quand l'utiliser

Vue

Découvrez ce que fait Vue nextTick(), pourquoi le DOM n'est pas mis à jour juste après un changement d'état, et comment utiliser await nextTick() et this.$nextTick() avec des exemples concrets en Vue 3.

Vue nextTick() qui attend la mise à jour du DOM après un changement d'état
Vue nextTick() : à quoi ça sert et quand l'utiliser

Vue nextTick est une fonction qui attend que Vue ait fini de mettre à jour le DOM après un changement d'état réactif. Quand vous écrivez count.value++, l'écran n'est pas mis à jour à la ligne suivante. Vue planifie la mise à jour, et nextTick() permet d'exécuter du code une fois qu'elle est terminée :

import { ref, nextTick } from 'vue';

const count = ref(0);

async function increment() {
  count.value++;
  // Le DOM affiche encore l'ancienne valeur ici

  await nextTick();
  // Le DOM est maintenant à jour
}

Vous n'en avez besoin que lorsque votre code lit ou manipule le DOM juste après un changement : donner le focus à un champ qui vient d'apparaître, faire défiler jusqu'à un nouveau message, mesurer un élément. Ce guide explique pourquoi Vue fonctionne ainsi, comment utiliser nextTick() avec la Composition API et l'Options API, et les erreurs qui donnent l'impression qu'il ne fonctionne pas. Chaque exemple a été vérifié avec Vue 3.5.

Pourquoi le DOM n'est pas mis à jour immédiatement

Vue ne modifie pas le DOM à chaque changement d'une valeur réactive. Il place la mise à jour du composant dans une file d'attente et applique tous les changements en attente d'un seul coup, un peu plus tard dans le même tour de la boucle d'événements. Prenons ce composant :

<script setup>
import { ref, nextTick } from 'vue';

const count = ref(0);
const counter = ref(null);

async function increment() {
  count.value++;
  console.log(counter.value.textContent); // '0'

  await nextTick();
  console.log(counter.value.textContent); // '1'
}
</script>

<template>
  <button @click="increment">
    Compteur : <span ref="counter">{{ count }}</span>
  </button>
</template>

Juste après count.value++, l'état vaut 1 mais le <span> contient toujours 0. Après await nextTick(), il contient 1.

Ce délai est volontaire. Si une fonction modifie trois fois la même valeur, Vue ne rend le composant qu'une seule fois :

function incrementThreeTimes() {
  count.value++;
  count.value++;
  count.value++;
  // Le composant n'est rendu qu'une fois, avec count = 3
}

Regrouper les mises à jour évite du travail inutile et garde les pages complexes rapides. La contrepartie, c'est que le DOM a un temps de retard sur votre état, et nextTick() sert justement à attendre qu'il rattrape ce retard.

Syntaxe de nextTick() en Vue 3

En Vue 3, nextTick s'importe depuis 'vue'. Il accepte un callback optionnel et retourne toujours une Promise :

function nextTick(callback?: () => void): Promise<void>

Vous pouvez l'utiliser de deux façons. Les deux attendent la même mise à jour du DOM :

import { nextTick } from 'vue';

// 1. Avec await (recommandé)
await nextTick();
// DOM à jour

// 2. Avec un callback
nextTick(() => {
  // DOM à jour
});

La forme avec await est plus lisible, surtout quand vous enchaînez plusieurs opérations, et c'est celle qu'utilise la documentation officielle de Vue sur nextTick() dans ses exemples.

this.$nextTick() avec l'Options API

Avec l'Options API, chaque instance de composant dispose d'une méthode $nextTick(). Elle fait la même chose que nextTick(), mais lie en plus this au composant courant dans le callback :

export default {
  data() {
    return { message: 'Bonjour' };
  },
  methods: {
    async updateMessage() {
      this.message = 'Mis à jour';

      await this.$nextTick();
      console.log(this.$refs.text.textContent); // 'Mis à jour'
    }
  }
};

this.$nextTick(function () { ... }) fonctionne aussi : dans cette fonction classique, this est l'instance du composant.

Comment nextTick fonctionne en interne

Quand une valeur réactive change, Vue ajoute la tâche de mise à jour du composant dans une file d'attente et planifie le traitement de cette file sous forme de microtâche, via une Promise déjà résolue. nextTick() retourne une Promise qui se résout après ce traitement. Deux conséquences :

  • Tout code synchrone placé après un changement d'état voit encore l'ancien DOM, car la file n'a pas encore été traitée.
  • nextTick() se résout avant n'importe quel callback de setTimeout(), puisque les microtâches passent avant la tâche suivante de la boucle d'événements.

Appeler nextTick() quand rien n'est en attente ne pose aucun problème : la Promise se résout simplement à la microtâche suivante.

Exemples concrets de nextTick dans Vue

1. Donner le focus à un champ qui vient d'apparaître

C'est le cas d'usage le plus courant. Quand un <input> est affiché avec v-if, il n'existe pas encore à la ligne où vous changez la condition, donc sa ref de template vaut null :

<script setup>
import { ref, nextTick } from 'vue';

const editing = ref(false);
const input = ref(null);

async function startEditing() {
  editing.value = true;
  // input.value vaut encore null ici

  await nextTick();
  input.value.focus();
}
</script>

<template>
  <input v-if="editing" ref="input" @blur="editing = false" />
  <button v-else @click="startEditing">Modifier</button>
</template>

2. Faire défiler un chat jusqu'au dernier message

Juste après l'ajout d'un message, la liste n'est pas encore plus haute. Attendez que le nouveau <li> soit rendu, puis faites défiler :

<script setup>
import { ref, nextTick } from 'vue';

const messages = ref([]);
const list = ref(null);
let nextId = 0;

async function addMessage(text) {
  messages.value.push({ id: nextId++, text });

  await nextTick();
  list.value.scrollTop = list.value.scrollHeight;
}
</script>

<template>
  <ul ref="list" class="chat">
    <li v-for="message in messages" :key="message.id">{{ message.text }}</li>
  </ul>
</template>

Sans nextTick(), le défilement s'arrêterait à chaque fois un message trop tôt.

3. Mesurer un élément après un changement de contenu

Les tailles et positions ne changent qu'une fois le DOM mis à jour. Lisez-les après nextTick(), pas avant :

const text = ref('');
const box = ref(null);
const height = ref(0);

async function setText(value) {
  text.value = value;

  await nextTick();
  height.value = box.value.offsetHeight;
}

4. Initialiser une librairie tierce sur un nouvel élément

Les librairies de graphiques, de cartes ou d'éditeurs ont besoin d'un vrai élément du DOM. Si cet élément apparaît avec v-if, créez l'instance après le prochain tick :

const showChart = ref(false);
const canvas = ref(null);

async function openChart() {
  showChart.value = true;

  await nextTick();
  new Chart(canvas.value, chartConfig);
}

5. Attendre le DOM dans les tests de composants

Les tests rencontrent le même délai. Avec Vue Test Utils, les méthodes comme trigger() et setValue() retournent déjà nextTick(), il suffit donc de les attendre. Quand vous modifiez l'état directement, attendez nextTick() vous-même :

import { mount } from '@vue/test-utils';
import { nextTick } from 'vue';
import Counter from './Counter.vue';

test('met à jour le compteur', async () => {
  const wrapper = mount(Counter);

  // trigger() retourne nextTick(), l'attendre suffit
  await wrapper.find('button').trigger('click');
  expect(wrapper.text()).toContain('1');

  // Un changement d'état direct demande un nextTick() explicite
  wrapper.vm.count = 5;
  await nextTick();
  expect(wrapper.text()).toContain('5');
});

nextTick vs setTimeout, watch et onUpdated

Plusieurs outils exécutent du code "après un changement". Ils ne s'exécutent pas au même moment :

Outil Quand il s'exécute À utiliser pour
nextTick() Juste après la mise à jour du DOM en attente Une action ponctuelle sur le DOM après une action de votre code
setTimeout(fn, 0) Dans une tâche ultérieure, après Vue et parfois après un rendu du navigateur Rien qui touche au DOM dans Vue : ça marche par hasard et peut provoquer un clignotement
watch(source, fn, { flush: 'post' }) Après la mise à jour du DOM, à chaque changement de la source Réagir à une valeur, quelle que soit l'origine du changement
onUpdated() Après chaque nouveau rendu du composant, quelle qu'en soit la raison Les rares cas qui doivent suivre chaque rendu

L'option des watchers mérite d'être connue. Par défaut, un watcher s'exécute avant la mise à jour du DOM, il voit donc l'ancien DOM. Avec flush: 'post', il s'exécute après, et vous n'avez pas besoin de nextTick() à l'intérieur :

import { watch } from 'vue';

// S'exécute avant la mise à jour du DOM : voit l'ancien DOM
watch(count, () => {
  console.log(counter.value.textContent); // '0'
});

// S'exécute après la mise à jour du DOM : voit le nouveau DOM
watch(count, () => {
  console.log(counter.value.textContent); // '1'
}, { flush: 'post' });

Une règle simple : utilisez nextTick() quand le travail sur le DOM est lié à une action précise (un clic, un envoi de formulaire), et un watcher flush: 'post' quand il doit avoir lieu à chaque changement d'une valeur.

Erreurs courantes quand nextTick "ne fonctionne pas"

Oublier de l'attendre

Appeler nextTick() seul sur une ligne ne sert à rien. Il faut soit l'attendre avec await, soit lui passer un callback :

// Incorrect : la ligne suivante n'attend pas
editing.value = true;
nextTick();
input.value.focus(); // TypeError: input.value is null

// Correct
editing.value = true;
await nextTick();
input.value.focus();

Enregistrer le callback avant de modifier l'état

Un callback passé à nextTick() avant le changement d'état peut s'exécuter avant la mise à jour qu'il était censé attendre :

// Incorrect : le callback est mis en file avant la mise à jour
nextTick(() => {
  console.log(counter.value.textContent); // toujours l'ancienne valeur
});
count.value++;

// Correct : modifier l'état d'abord, puis attendre
count.value++;
await nextTick();
console.log(counter.value.textContent); // nouvelle valeur

Croire que nextTick attend vos données

nextTick() attend le rendu de Vue, pas un appel API. Si les données sont encore en cours de chargement, il n'y a rien de nouveau à afficher. Attendez d'abord les données, puis le DOM :

async function loadUsers() {
  users.value = await fetchUsers(); // 1. attendre les données
  await nextTick();                 // 2. attendre le DOM
  list.value.scrollTop = 0;
}

L'utiliser dans onMounted() pour le DOM du composant

Quand onMounted() s'exécute, le template du composant est déjà dans le DOM et ses refs de template sont définies. Envelopper ce code dans nextTick() n'apporte rien. Il n'est utile que si onMounted() modifie lui-même l'état puis lit le résultat dans le DOM.

Appeler Vue.nextTick() en Vue 3

Vue 3 a supprimé la plupart des API globales pour que les bundlers puissent éliminer ce que vous n'utilisez pas. Vue.nextTick() n'existe plus : importez nextTick depuis 'vue', ou utilisez this.$nextTick() avec l'Options API.

nextTick en Vue 2 et en Vue 3

  • Vue 2 : disponible via la méthode globale Vue.nextTick() et via this.$nextTick(). Il retourne une Promise quand il est appelé sans callback. En interne, il privilégie les Promises et se rabat sur des mécanismes plus anciens dans les environnements qui n'en disposent pas.
  • Vue 3 : s'importe avec import { nextTick } from 'vue', retourne toujours une Promise, et this.$nextTick() reste disponible avec l'Options API.

Le principe reste le même dans les deux versions : modifier l'état, attendre le prochain tick, puis travailler avec le DOM. Vue 2 est en fin de vie depuis le 31 décembre 2023, le nouveau code doit donc cibler Vue 3.

Questions fréquentes

À quoi sert nextTick dans Vue ?

Il attend que Vue ait appliqué au DOM les changements d'état en attente, puis résout sa Promise ou exécute son callback. Utilisez-le quand votre code doit lire ou modifier le DOM mis à jour juste après un changement.

nextTick retourne-t-il une Promise ?

Oui. En Vue 3, nextTick() retourne toujours une Promise, vous pouvez donc écrire await nextTick(). Le callback est optionnel.

Quelle différence entre nextTick() et this.$nextTick() ?

Ils attendent la même mise à jour. nextTick() s'importe depuis 'vue' et s'utilise avec la Composition API. this.$nextTick() est la version Options API, qui lie this à l'instance du composant dans le callback.

nextTick est-il équivalent à setTimeout(fn, 0) ?

Non. nextTick() est une microtâche liée à la file de mises à jour de Vue et s'exécute juste après la mise à jour du DOM. setTimeout() attend une tâche ultérieure : il s'exécute plus tard et le navigateur peut afficher un état intermédiaire entre les deux.

Pourquoi ma ref de template vaut-elle encore null après un changement ?

L'élément est créé lors de la prochaine mise à jour du DOM, pas au moment où vous modifiez l'état. Placez await nextTick() entre le changement d'état et la ligne qui utilise la ref.

Conclusion

Vue regroupe les mises à jour du DOM pour des raisons de performance, ce qui signifie que le DOM a toujours un léger retard sur votre état après un changement. Vue nextTick comble cet écart : modifiez l'état, faites await nextTick(), puis travaillez avec le DOM. Utilisez-le pour le focus, le défilement et les mesures juste après une action, préférez un watcher flush: 'post' quand le travail doit suivre chaque changement d'une valeur, et laissez setTimeout() de côté.

Si le this des callbacks de l'Options API vous semble encore flou, notre guide de la méthode bind() en JavaScript explique comment il est défini. Pour aller plus loin sur les Promises et les timers, lisez comment faire une pause (wait / sleep) en Node.js.

Commencez à créer avec Axentix

Prêt à créer des sites web exceptionnels ? Commencez avec le framework Axentix dès aujourd'hui.

Commencer

Articles similaires