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 desetTimeout(), 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 viathis.$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, etthis.$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.