Skip to content

Vue 3 Aide-mémoire

Framework JavaScript progressif pour construire des interfaces utilisateur.

01

Premiers pas

Hello World et commentaires

Une app Vue 3 commence par createApp() et mount() sur un élément DOM. L'interpolation utilise les doubles accolades {{ }} pour rendre des données réactives. Les commentaires HTML apparaissent dans le DOM rendu ; pour des commentaires qui ne fuient pas, utilisez /* */ dans les blocs <script>.

vue3
<!-- index.html -->
<div id="app">
  <p>{{ message }}</p>
  <!-- This is an HTML comment, visible in DOM -->
</div>

<script type="module">
  import { createApp } from 'vue'

  createApp({
    data() {
      return { message: 'Hello Vue 3!' }
    }
  }).mount('#app')
</script>

Structure SFC (composant monofichier)

Un SFC regroupe template, script et style dans un seul fichier .vue. <script setup> est la syntaxe recommandée pour l'API Composition — concise et sans code répétitif. Les styles scoped ne s'appliquent qu'au composant courant, prévenant les fuites. Chaque SFC compile vers un module JavaScript.

vue3
<template>
  <button @click="count++">Count: {{ count }}</button>
</template>

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<style scoped>
button { color: #42B883; }
</style>

Instance d'app et mount

createApp retourne une instance d'application qui se limite à elle-même — pas d'état Vue global, donc on peut monter plusieurs apps indépendantes sur une page. Enregistrez les plugins, fournissez des valeurs globales et réglez la config avant d'appeler mount(). Après mount, les changements de config ultérieurs ne prennent pas effet.

vue3
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

// global config / plugins before mounting
app.config.errorHandler = (err) => console.error(err)
app.provide('apiKey', '12345')

app.mount('#app')

Scaffolding de projet (Vite)

npm create vue@latest est l'outil de scaffolding officiel, offrant TypeScript, Router, Pinia et Vitest en option. Il utilise Vite pour un démarrage instantané du serveur de dev et l'HMR. create-vite est l'outil de plus bas niveau si vous voulez un template minimal sans les opinions de Vue.

vue3
# scaffold a new Vue project with Vite
npm create vue@latest my-app
cd my-app
npm install
npm run dev       # start dev server (HMR)
npm run build     # production build to /dist

# or with create-vite directly
npm create vite@latest my-app -- --template vue-ts

defineOptions et defineProps

defineProps, defineEmits et defineOptions sont des macros de compilation — pas besoin de les importer. defineProps déclare le contrat de props du composant avec validation à l'exécution. defineOptions permet de régler name, inheritAttrs et d'autres options non exprimables directement dans <script setup>.

vue3
<script setup>
// declare props with types and defaults
const props = defineProps({
  title: String,
  count: { type: Number, default: 0 }
})

// declare emits
const emit = defineEmits(['update', 'delete'])

// additional non-reactive options
defineOptions({ name: 'MyButton', inheritAttrs: false })
</script>
02

Syntaxe de template

Interpolation de texte

{{ }} rend du texte en sécurité (échappé HTML). v-once fige une liaison après le premier rendu pour du contenu statique. v-html injecte du HTML brut — seulement sur du contenu de confiance pour éviter le XSS. Dans {{ }} on peut utiliser n'importe quelle expression JavaScript unique, mais pas d'instructions comme des affectations ou des déclarations var.

vue3
<template>
  <p>{{ message }}</p>
  <!-- renders the value of message -->

  <!-- one-time binding (no updates after render) -->
  <span v-once>{{ initialCount }}</span>

  <!-- raw HTML (sanitize to avoid XSS!) -->
  <div v-html="rawHtmlContent"></div>

  <!-- expressions are supported -->
  <p>{{ count * 2 }}</p>
  <p>{{ isReady ? 'Yes' : 'No' }}</p>
  <p>{{ message.split('').reverse().join('') }}</p>
</template>

Liaison d'attributs

v-bind (raccourci :) lie les attributs de façon réactive. Pour class, on peut passer un objet (les clés truthy s'appliquent), un tableau ou une chaîne. style accepte un objet avec clés camelCase ou kebab-case. La syntaxe d'argument dynamique :[expr] laisse le nom d'attribut lui-même réactif — utile pour les noms d'événements ou les attributs localisés.

vue3
<template>
  <!-- bind an attribute -->
  <img v-bind:src="imageUrl" />
  <img :src="imageUrl" />  <!-- shorthand -->

  <!-- bind class -->
  <div :class="{ active: isActive, error: hasError }"></div>
  <div :class="['btn', isActive && 'active']"></div>

  <!-- bind style -->
  <div :style="{ color: textColor, fontSize: size + 'px' }"></div>

  <!-- dynamic attribute name -->
  <button :[eventName]="handler">Click</button>
</template>

Attributs booléens et multi-valeurs

Pour les attributs booléens comme disabled ou checked, Vue ne rend l'attribut que si la valeur est truthy. class et style sont spéciaux : Vue fusionne valeurs statiques et liées au lieu de les remplacer. Pour les champs de formulaire, préférez v-model à la liaison manuelle :value et @input.

vue3
<template>
  <!-- boolean attribute: presence depends on value -->
  <input :disabled="isDisabled" />
  <button :disabled="!canSubmit">Submit</button>

  <!-- class merging: bound class merges with static class -->
  <div class="card" :class="{ highlighted: isFeatured }"></div>

  <!-- style merging: bound style merges with static style -->
  <div style="color: red" :style="{ fontSize: '14px' }"></div>

  <!-- form attributes: value is bound with v-model instead -->
  <input v-model="text" />
</template>

Modificateurs et expressions

Les modificateurs sont postfixés par un point, indiquant un traitement spécial. Les modificateurs d'événement (.prevent, .stop, .once, .self) enveloppent le handler avec la méthode DOM correspondante. Les modificateurs de touche (.enter, .esc, .ctrl) filtrent les événements par touche. Les modificateurs de v-model (.trim, .number, .lazy) transforment la valeur d'entrée avant affectation.

vue3
<template>
  <!-- .prevent calls event.preventDefault() -->
  <form @submit.prevent="onSubmit">...</form>

  <!-- .stop calls event.stopPropagation() -->
  <button @click.stop="doStuff">Click</button>

  <!-- .once runs handler only one time -->
  <button @click.once="init">Init</button>

  <!-- .trim and .lazy modifiers on v-model -->
  <input v-model.trim="email" />
  <input v-model.lazy="text" />

  <!-- chain multiple modifiers -->
  <input @keyup.enter.ctrl="onCombo" />
</template>

Références de template

Les template refs donnent un accès direct aux éléments DOM. Déclarez un ref() du même nom que l'attribut ref — Vue affecte le nœud DOM après le mount. Accédez dans onMounted (ou après) ; avant le mount, la ref est null. Pour v-for, la ref devient un tableau d'éléments. Évitez les refs quand des flux de données réactifs suffiraient.

vue3
<script setup>
import { ref, onMounted } from 'vue'

// declare a ref matching the template ref attribute
const inputEl = ref(null)

onMounted(() => {
  // access the DOM node after mount
  inputEl.value.focus()
})
</script>

<template>
  <input ref="inputEl" />
</template>
03

Directives

v-if / v-else-if / v-else

v-if rend les éléments conditionnellement — ils s'ajoutent/se retirent du DOM. v-else-if et v-else s'enchaînent après un v-if précédent. Enveloppez plusieurs éléments dans un <template v-if> quand vous ne voulez pas d'élément d'enveloppe supplémentaire. v-if a un coût de bascule plus élevé (création DOM) mais un coût initial plus bas que v-show quand la condition est fausse.

vue3
<template>
  <div v-if="type === 'A'">Type A</div>
  <div v-else-if="type === 'B'">Type B</div>
  <div v-else-if="type === 'C'">Type C</div>
  <div v-else>Unknown type</div>

  <!-- use <template> for invisible wrapper -->
  <template v-if="showHeader">
    <h1>Title</h1>
    <p>Subtitle</p>
  </template>
</template>

v-show vs v-if

Utilisez v-if quand la condition change rarement — les éléments se détruisent et recréent, économisant le coût de rendu quand cachés. Utilisez v-show pour les éléments fréquemment basculés (onglets, dropdowns) — l'élément reste dans le DOM et seul display:none bascule, donc la bascule est bon marché. v-show ne marche pas avec <template> ni v-else.

vue3
<template>
  <!-- v-if removes from DOM when false -->
  <p v-if="isVisible">I'm created/destroyed</p>

  <!-- v-show just toggles display:none -->
  <p v-show="isVisible">I'm always in DOM, just hidden</p>
</template>

<script setup>
import { ref } from 'vue'
const isVisible = ref(true)
</script>

v-for et :key

v-for itère tableaux, objets ou plage de nombres. L'attribut :key est REQUIS pour l'identité de suivi — il permet à Vue de réutiliser efficacement les nœuds DOM lors des réordonnancements. Utilisez un id unique stable comme clé ; jamais l'index du tableau (casse quand les éléments bougent). v-for a une priorité plus haute que v-if sur le même élément — évitez les deux sur un même élément.

vue3
<template>
  <!-- iterate over array -->
  <li v-for="item in items" :key="item.id">
    {{ item.name }}
  </li>

  <!-- iterate with index -->
  <li v-for="(item, index) in items" :key="item.id">
    {{ index }}: {{ item.name }}
  </li>

  <!-- iterate over object -->
  <li v-for="(value, key) in user" :key="key">
    {{ key }}: {{ value }}
  </li>

  <!-- range (1 to n) -->
  <span v-for="n in 10" :key="n">{{ n }}</span>
</template>

Liaisons v-model

v-model est une liaison bidirectionnelle pour les champs de formulaire : il synchronise la valeur d'entrée avec l'état réactif. Une checkbox unique se lie à un booléen ; plusieurs checkboxes avec le même v-model se lient à un tableau des valeurs cochées. Utilisez les modificateurs : .lazy (sync au change au lieu d'input), .number (cast en nombre), .trim (retire les espaces).

vue3
<template>
  <!-- text input -->
  <input v-model="text" />

  <!-- multi-line textarea -->
  <textarea v-model="message"></textarea>

  <!-- checkbox (single = boolean, multiple = array) -->
  <input type="checkbox" v-model="isChecked" />
  <input type="checkbox" value="apple" v-model="fruits" />
  <input type="checkbox" value="banana" v-model="fruits" />

  <!-- radio -->
  <input type="radio" value="A" v-model="picked" />

  <!-- select -->
  <select v-model="selected">
    <option value="a">A</option>
    <option value="b">B</option>
  </select>
</template>

Directives personnalisées

Les directives custom permettent de manipuler directement les éléments DOM. Dans <script setup>, toute variable nommée vQuelqueChose (camelCase) est automatiquement disponible comme v-quelque-chose dans le template. L'objet directive a des hooks de cycle de vie : mounted, updated, unmounted, etc. Préférez les composants aux directives quand vous avez besoin de réactivité — les directives sont pour du travail DOM bas niveau comme le focus, tooltips ou drag.

vue3
<script setup>
// local directive: function form (mounted + updated)
const vFocus = {
  mounted: (el) => el.focus()
}

// global registration
// app.directive('focus', { mounted: el => el.focus() })
</script>

<template>
  <input v-focus />
</template>
04

Propriétés calculées

Computed de base

computed crée un getter mis en cache qui ne réévalue que quand ses dépendances changent. Contrairement à un appel de méthode, les accès répétés retournent la valeur cachée jusqu'à mise à jour d'une dépendance. Dans <script>, accès via .value ; dans les templates, Vue auto-déballe. Préférez computed aux méthodes dès que la valeur dépend de l'état réactif — plus rapide et déclaratif.

vue3
<script setup>
import { ref, computed } from 'vue'

const firstName = ref('John')
const lastName = ref('Doe')

// computed caches based on dependencies
const fullName = computed(() => {
  return firstName.value + ' ' + lastName.value
})

// access via .value in script
console.log(fullName.value)  // 'John Doe'
</script>

<template>
  <!-- use without .value in template -->
  <p>{{ fullName }}</p>
</template>

Computed inscriptible

Par défaut computed est en lecture seule, mais on peut fournir un getter et un setter. Le setter s'invoque quand on affecte à .value. Utile pour la liaison bidirectionnelle sur un état dérivé, ex. synchroniser une saisie de nom complet vers des champs prénom/nom. Attention aux boucles infinies — les setters ne doivent pas directement régler les propres dépendances du computed d'une façon qui se redéclenche.

vue3
<script setup>
import { ref, computed } from 'vue'

const firstName = ref('John')
const lastName = ref('Doe')

const fullName = computed({
  get() {
    return firstName.value + ' ' + lastName.value
  },
  set(newValue) {
    [firstName.value, lastName.value] = newValue.split(' ')
  }
})

// assignment triggers the setter
fullName.value = 'Jane Smith'
</script>

Computed vs méthodes

Les computed cachent leur résultat selon les dépendances — ils ne ré-tournent que quand items change. Les méthodes ré-tournent à chaque rendu peu importe ce qui a changé. Utilisez computed pour les valeurs dérivées de l'état réactif ; les méthodes pour les actions prenant des paramètres ou ayant des effets de bord. Computed clarifie aussi l'intention : « cette valeur est dérivée » vs « fais ceci ».

vue3
<script setup>
import { ref, computed } from 'vue'

const items = ref([1, 2, 3, 4, 5])

// computed: cached, re-runs only if items changes
const doubled = computed(() =>
  items.value.map(x => x * 2)
)

// method: re-runs on every render
function getDoubled() {
  return items.value.map(x => x * 2)
}
</script>

<template>
  <!-- cached, no recompute on unrelated re-renders -->
  <p>{{ doubled }}</p>

  <!-- re-invoked on every render -->
  <p>{{ getDoubled() }}</p>
</template>

Pièges des computed getter

Les getters de computed doivent être purs : pas d'effets de bord (pas de mutations, pas d'async, pas de fetch). N'appelez pas Date.now() ni Math.random() — ils ne sont pas réactifs donc le computed ne se mettra pas à jour. Si vous avez besoin d'un effet de bord, utilisez un watcher. Si vous avez besoin d'async, computed n'attendra pas — utilisez watch + une ref, ou un setup async avec Suspense.

vue3
<script setup>
import { ref, computed } from 'vue'

const date = ref(new Date())

// BAD: non-reactive Date.now() — won't update
const badTime = computed(() => Date.now())

// BAD: side effect inside computed
const count = ref(0)
const bad = computed(() => {
  count.value++   // never mutate state in computed!
  return count.value
})

// GOOD: pure function of reactive state
const formatted = computed(() =>
  date.value.toLocaleDateString()
)
</script>

Computed dans l'API Options

Dans l'API Options, déclarez les computed dans l'option computed. Ils s'accèdent comme this.total (pas de .value, pas de parenthèses) — Vue auto-déballe. Le computed inscriptible utilise des fonctions get/set. Les propriétés calculées s'exposent sur l'instance du composant à côté de data et methods, toutes accessibles via this.

vue3
<script>
export default {
  data() {
    return { price: 100, quantity: 2 }
  },
  computed: {
    total() {
      return this.price * this.quantity
    },
    discounted: {
      get() { return this.total * 0.9 },
      set(v) { this.price = v / 0.9 / this.quantity }
    }
  },
  methods: {
    checkout() { console.log(this.total) }
  }
}
</script>
05

Watchers

watch de base

watch exécute un callback quand la source surveillée change. La source peut être une ref, une propriété d'objet réactif (via getter) ou un tableau de sources. Le callback reçoit (nouvelleValeur, ancienneValeur). Utilisez un getter () => x.y pour surveiller des propriétés réactives imbriquées. Les watchers servent aux effets de bord (fetch, log, persistance) — pas à dériver de l'état (utilisez computed).

vue3
<script setup>
import { ref, watch } from 'vue'

const question = ref('')

// watch a ref
watch(question, (newValue, oldValue) => {
  console.log('changed from', oldValue, 'to', newValue)
})

// watch a getter (computed source)
watch(
  () => question.value.length,
  (newLen) => {
    if (newLen > 100) console.warn('Too long!')
  }
)
</script>

Deep watch et immediate

deep: true fait que watch se déclenche sur les changements de toute propriété imbriquée d'un objet — utile mais coûteux sur les grandes structures. immediate: true déclenche le callback immédiatement au setup (oldValue undefined au premier appel). Évitez le deep watch sur d'énormes objets — préférez surveiller un getter précis () => obj.champPrecis pour une meilleure performance.

vue3
<script setup>
import { reactive, watch } from 'vue'

const user = reactive({
  name: 'Alice',
  address: { city: 'NYC', zip: '10001' }
})

// deep: watch nested property changes
watch(
  () => user.address,
  (newAddr) => console.log('address changed', newAddr),
  { deep: true }
)

// immediate: run callback right away
watch(
  user,
  (val) => saveToServer(val),
  { deep: true, immediate: true }
)
</script>

watchEffect (auto-suivi)

watchEffect exécute le callback immédiatement et suit automatiquement toute dépendance réactive accédée dedans. Dès qu'une dépendance suivie change, le callback ré-tourne. Contrairement à watch, on ne spécifie pas de source — elle s'infère. Utilisez watchEffect quand vous n'avez pas besoin de l'oldValue et voulez un suivi automatique des dépendances. Utile pour établir des abonnements lisant plusieurs sources réactives.

vue3
<script setup>
import { ref, watchEffect } from 'vue'

const a = ref(1)
const b = ref(2)

// runs immediately and tracks dependencies automatically
watchEffect(() => {
  console.log('a + b =', a.value + b.value)
})
// logs: a + b = 3

a.value = 10  // logs: a + b = 12

// stop the watcher
const stop = watchEffect(() => { /* ... */ })
stop()  // cleanup
</script>

watch vs watchEffect

Choisissez watch quand vous avez besoin de : oldValue, exécution paresseuse (sauter le premier run), ou de surveiller une source précise explicitement. Choisissez watchEffect quand : vous voulez une exécution immédiate, vous n'avez pas besoin de l'oldValue, ou vous avez des effets de bord touchant plusieurs valeurs réactives et voulez un suivi automatique. watch avec une source tableau vous donne des tableaux de nouvelles/anciennes valeurs dans le callback.

vue3
<script setup>
import { ref, watch, watchEffect } from 'vue'

const count = ref(0)

// watch: lazy, explicit source, has oldValue
watch(count, (newVal, oldVal) => {
  console.log('count changed:', oldVal, '->', newVal)
})

// watchEffect: eager, auto-tracked, no oldValue
watchEffect(() => {
  console.log('count is', count.value)
})
// logs immediately: count is 0

// watch multiple sources
const a = ref(1), b = ref(2)
watch([a, b], ([newA, newB], [oldA, oldB]) => {
  console.log('a or b changed')
})
</script>

Nettoyage et flush des watchers

Le callback onCleanup (3e argument) enregistre une fonction de nettoyage qui tourne avant la prochaine invocation du watcher — parfait pour annuler des requêtes en vol, effacer des timers ou se désabonner. flush: 'post' exécute le watcher après que Vue a mis à jour le DOM (utile quand on doit lire un DOM à jour). 'sync' s'exécute synchrone au changement de dépendance — rarement requis et peut causer des soucis de performance.

vue3
<script setup>
import { ref, watch } from 'vue'

const id = ref(1)

// cleanup function: runs before next callback
watch(id, (newId, oldId, onCleanup) => {
  const controller = new AbortController()
  fetch(`/api/user/${newId}`, { signal: controller.signal })
    .then(r => r.json())

  // cancel previous request when id changes again
  onCleanup(() => controller.abort())
}, { flush: 'post' })

// flush: 'pre' (default) | 'post' (after DOM update) | 'sync'
</script>
06

Rendu conditionnel

v-if vs v-show

v-if ajoute/retire réellement les éléments du DOM — coût initial plus élevé mais coût nul quand caché. v-show rend toujours l'élément et bascule display:none — bascule moins chère mais l'élément existe même caché. Utilisez v-if pour des conditionnels changeant rarement (ou quand les éléments cachés ne devraient pas exister du tout). Utilisez v-show pour l'UI fréquemment basculée comme onglets, dropdowns, modales.

vue3
<template>
  <!-- v-if: element removed from DOM when false -->
  <div v-if="isLoggedIn">Welcome back</div>

  <!-- v-show: element stays, display toggles -->
  <div v-show="isLoggedIn">Welcome back</div>
</template>

<!-- v-show compiles to: -->
<!-- <div style="display: none;">Welcome back</div> when false -->

<!-- v-if does not render the element at all when false -->

Chaîne v-if avec v-else

v-else-if et v-else doivent suivre immédiatement un élément v-if (ou un autre v-else-if) — aucun autre élément ne peut s'intercaler. La chaîne s'évalue de haut en bas et s'arrête à la première condition truthy. Le v-else final attrape tous les cas restants. Ce pattern est génial pour l'UI à états (chargement, erreur, vide, succès).

vue3
<template>
  <div v-if="status === 'loading'">Loading...</div>
  <div v-else-if="status === 'error'">Error occurred</div>
  <div v-else-if="status === 'empty'">No items</div>
  <div v-else>
    <ul>
      <li v-for="item in items" :key="item.id">{{ item.name }}</li>
    </ul>
  </div>
</template>

Enveloppe <template> pour v-if

<template> est une enveloppe logique qui ne se rend pas dans le DOM — parfait pour grouper plusieurs éléments sous un seul v-if ou v-for sans ajouter de HTML supplémentaire. Cela garde votre balisage sémantique (pas de divs égarés). Pour v-for sur template, il faut quand même :key sur l'élément template lui-même.

vue3
<template>
  <!-- group elements under one condition, no wrapper div -->
  <template v-if="showProfile">
    <h2>{{ user.name }}</h2>
    <p>{{ user.bio }}</p>
    <button @click="edit">Edit</button>
  </template>

  <!-- combine v-if with v-for on template -->
  <template v-for="item in items" :key="item.id">
    <dt>{{ item.term }}</dt>
    <dd>{{ item.def }}</dd>
  </template>
</template>

Priorité v-if vs v-for

N'utilisez jamais v-if et v-for sur le même élément. Dans Vue 3, v-if a une priorité plus haute, donc il s'exécute avant v-for — la variable de boucle n'est pas encore disponible, causant des erreurs. À la place, filtrez le tableau avec une propriété calculée (préféré) ou un .filter() inline. Utilisez un <template v-for> enveloppant avec un v-if interne si nécessaire.

vue3
<template>
  <!-- AVOID: v-if and v-for on same element -->
  <!-- In Vue 3, v-if has higher priority than v-for -->
  <!-- so 'item' is not defined when v-if evaluates -->
  <li v-for="item in items" v-if="item.active" :key="item.id">
    {{ item.name }}
  </li>

  <!-- GOOD: filter first, then iterate -->
  <li
    v-for="item in items.filter(i => i.active)"
    :key="item.id"
  >
    {{ item.name }}
  </li>

  <!-- BEST: use computed for the filtered list -->
</template>

Transition avec v-if

Enveloppez un élément v-if (ou v-show) dans <Transition> pour animer entrée/sortie. Vue ajoute des classes aux bons moments : v-enter-from, v-enter-active, v-enter-to (et v-leave-*). Définissez des transitions CSS sur ces classes. name='fade' remplace le préfixe 'v-' par 'fade-'. Transition ne supporte qu'un seul élément enfant — utilisez TransitionGroup pour les listes.

vue3
<template>
  <Transition name="fade">
    <p v-if="show">Hello</p>
  </Transition>
</template>

<style>
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>
07

Rendu de listes

v-for avec tableaux

v-for itère les tableaux, exposant chaque élément et (optionnellement) l'index. Liez TOUJOURS :key à une valeur unique stable comme item.id — cela permet à Vue d'apparier les vieux et nouveaux nœuds lors du réordonnancement, préservant efficacement l'état des composants et le DOM. Utiliser l'index comme clé casse quand les éléments s'insèrent/se retirent/se réordonnent, causant des bugs subtils.

vue3
<script setup>
import { ref } from 'vue'
const items = ref([
  { id: 1, name: 'Apple' },
  { id: 2, name: 'Banana' },
  { id: 3, name: 'Cherry' }
])
</script>

<template>
  <!-- always provide :key with stable unique id -->
  <li v-for="item in items" :key="item.id">
    {{ item.name }}
  </li>

  <!-- with index (avoid as :key) -->
  <li v-for="(item, index) in items" :key="item.id">
    {{ index + 1 }}. {{ item.name }}
  </li>
</template>

v-for avec objets et plage

v-for sur un objet itère les valeurs par défaut ; le second argument est la clé, le troisième l'index. L'ordre d'itération des objets suit Object.keys() (ordre d'insertion pour les clés chaînes). v-for avec un nombre n itère de 1 à n (inclusif, pas 0 à n-1). Pour les listes filtrées ou triées, préférez une propriété calculée à la logique inline pour la lisibilité et le cache.

vue3
<template>
  <!-- iterate object: (value, key, index) -->
  <div v-for="(value, key, index) in user" :key="key">
    {{ index }}. {{ key }}: {{ value }}
  </div>

  <!-- iterate a number range (1 to n inclusive) -->
  <span v-for="n in 10" :key="n">{{ n }} </span>
  <!-- 1 2 3 4 5 6 7 8 9 10 -->

  <!-- use v-for of computed for derived lists -->
  <li v-for="todo in doneTodos" :key="todo.id">
    {{ todo.text }}
  </li>
</template>

Détection des changements de liste

Vue 3 utilise la réactivité par Proxy, donc muter les tableaux avec push, pop, splice, sort, reverse déclenche tous des mises à jour — pas de caveats spéciaux (contrairement à Vue 2). Remplacer tout le tableau (items.value = newArray) marche aussi car le setter de value de la ref déclenche la réactivité. filter/map produisent de nouveaux tableaux — réaffectez-les pour mettre à jour.

vue3
<script setup>
import { ref } from 'vue'

const items = ref([1, 2, 3])

// MUTATION methods (Vue 3 detects these via Proxy)
items.value.push(4)        // add
items.value.pop()          // remove last
items.value.splice(1, 1)   // remove at index
items.value.sort()         // sort

// REPLACEMENT (always reactive)
items.value = items.value.filter(n => n > 1)
items.value = [...items.value, 5]
</script>

TransitionGroup pour les listes

TransitionGroup anime les listes v-for : entrée, sortie ET déplacement (quand les éléments changent de position). Contrairement à Transition, il rend un vrai élément (réglé via tag). Chaque enfant DOIT avoir un :key unique. La classe .list-move anime les éléments glissant vers leurs nouvelles positions quand la liste se réordonne — un effet poli que le CSS simple ne peut pas atteindre. leave-active exige position: absolute pour des mouvements doux.

vue3
<template>
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">
      {{ item.text }}
    </li>
  </TransitionGroup>
</template>

<style>
.list-enter-active, .list-leave-active {
  transition: all 0.5s ease;
}
.list-enter-from, .list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}
/* animate items moving to new positions */
.list-move {
  transition: transform 0.5s ease;
}
</style>

Performance : v-memo

v-memo est un indice d'optimisation. Vue saute le re-rendu de l'élément sauf si une des valeurs du tableau de dépendances change. Pour les grandes listes où la plupart des éléments ne changent pas à chaque mise à jour, cela peut réduire drastiquement les re-rendus. N'utilisez-le qu'après avoir mesuré un problème de performance — l'optimisation prématurée ajoute de la complexité et un risque d'UI périmée.

vue3
<template>
  <!-- skip re-render of this item unless 'id' or 'selected' changes -->
  <div
    v-for="item in hugeList"
    :key="item.id"
    v-memo="[item.id, item.id === selectedId]"
  >
    {{ item.name }} — {{ item.id === selectedId ? '★' : '' }}
  </div>
</template>
08

Gestion des événements

Handlers inline

@click (raccourci de v-on:click) lie un handler de clic. Les instructions inline (count++) conviennent aux cas simples. Un nom de méthode (greet) reçoit automatiquement l'événement natif en premier argument. Pour passer des arguments custom ET l'événement, appelez la méthode explicitement avec $event : greet('salut', $event).

vue3
<script setup>
import { ref } from 'vue'
const count = ref(0)
const name = ref('Vue')

function greet(event) {
  alert('Hello ' + name.value)
  // event is the native DOM event
  console.log(event.target.tagName)
}
</script>

<template>
  <!-- inline statement -->
  <button @click="count++">Add</button>

  <!-- method reference (auto-receives event) -->
  <button @click="greet">Greet</button>

  <!-- call with custom args (use $event for native event) -->
  <button @click="greet($event)">Greet</button>
</template>

Modificateurs d'événements

Les modificateurs d'événement s'enchaînent après le nom d'événement avec un point. .prevent et .stop sont les plus courants (soumission de formulaire, bouillonnement). .self garantit que le handler ne se déclenche que si l'élément lui-même (pas un enfant) est cliqué. .passive dit au navigateur que le handler n'appellera pas preventDefault, permettant un défilement plus doux — important pour les handlers tactiles/scroll.

vue3
<template>
  <!-- .prevent: call preventDefault() -->
  <form @submit.prevent="onSubmit">...</form>

  <!-- .stop: call stopPropagation() -->
  <div @click="outer">
    <button @click.stop="inner">Won't bubble</button>
  </div>

  <!-- .self: only trigger if event.target === current element -->
  <div @click.self="onSelf">Only direct clicks</div>

  <!-- .once: handler removed after first invocation -->
  <button @click.once="init">Init once</button>

  <!-- .capture: use capture phase instead of bubble -->
  <div @click.capture="onCapture">...</div>

  <!-- .passive: improve scroll perf (no preventDefault) -->
  <div @scroll.passive="onScroll">...</div>
</template>

Modificateurs de touches et système

Les modificateurs de touche filtrent les événements clavier par nom de touche (.enter, .esc, .delete, .space, .tab, .up, .down, .left, .right). Les modificateurs système (.ctrl, .alt, .shift, .meta) exigent que cette touche soit maintenue. .exact garantit qu'aucun AUTRE modificateur système n'est maintenu — @click.ctrl.exact ne se déclenche que sur Ctrl+Clic, pas Ctrl+Shift+Clic. Utilisez le kebab-case pour les touches que Vue n'aliasse pas (page-down).

vue3
<template>
  <!-- key modifiers: only fire on specific keys -->
  <input @keyup.enter="submit" />
  <input @keyup.esc="cancel" />
  <input @keyup.delete="remove" />

  <!-- system modifiers: ctrl, alt, shift, meta -->
  <button @click.ctrl="openInNewTab">Ctrl+Click</button>
  <input @keyup.alt.enter="altEnter" />

  <!-- .exact: no other modifiers can be pressed -->
  <button @click.ctrl.exact="onCtrlOnly">Ctrl only</button>

  <!-- any key code via kebab-case (deprecated but works) -->
  <input @keyup.page-down="onPageDown" />
</template>

Événements custom avec emit

Les composants enfants émettent des événements pour communiquer vers le haut. defineEmits déclare les noms d'événements (pour la validation et les indices IDE). Le parent écoute avec @nom-evenement. Les payloads passent en arguments supplémentaires à emit et sont reçus par le handler du parent. Par convention, utilisez des noms d'événements kebab-case dans les templates (mon-evenement), camelCase dans defineEmits (monEvenement) — Vue convertit automatiquement.

vue3
<!-- ChildButton.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])

function onClick() {
  // emit with payload
  emit('increment', 1)
}
</script>

<template>
  <button @click="onClick">+1</button>
</template>

<!-- Parent.vue -->
<template>
  <ChildButton @increment="onIncrement" @delete="remove" />
</template>

<script setup>
function onIncrement(amount) {
  console.log('incremented by', amount)
}
</script>

v-model sur les composants

defineModel() est la macro moderne (Vue 3.4+) pour la liaison bidirectionnelle sur les composants — elle retourne une ref qui se synchronise automatiquement avec le v-model du parent. Pour plusieurs liaisons, utilisez des modèles nommés : v-model:champ. Sous le capot, cela émet 'update:modelValue' (ou 'update:champ') et le parent synchronise la ref liée. Le vieux code utilise defineProps + defineEmits manuellement.

vue3
<!-- CustomInput.vue -->
<script setup>
const model = defineModel()
</script>

<template>
  <input :value="model" @input="model = $event.target.value" />
</template>

<!-- Parent.vue -->
<template>
  <CustomInput v-model="text" />
</template>

<!-- multiple v-models (Vue 3.4+) -->
<template>
  <UserForm v-model:name="name" v-model:email="email" />
</template>
09

Liaisons de formulaires

Text et textarea

v-model sur les inputs texte se synchronise à chaque événement input. Pour textarea, mettez v-model directement sur l'élément (pas en :value — le contenu multiligne dans un attribut ne marchera pas). Modificateurs : .lazy se synchronise au blur/change (moins de mises à jour), .trim retire les espaces, .number caste la valeur en Number. Enchaînez les modificateurs : v-model.lazy.trim.

vue3
<script setup>
import { ref } from 'vue'
const text = ref('')
const message = ref('')
</script>

<template>
  <!-- text input: binds on every keystroke -->
  <input v-model="text" placeholder="Type here" />
  <p>You typed: {{ text }}</p>

  <!-- textarea: insert tags inside, not :value -->
  <textarea v-model="message" rows="4"></textarea>
  <p>Preview: {{ message }}</p>

  <!-- .lazy: sync on 'change' (blur) instead of 'input' -->
  <input v-model.lazy="text" />

  <!-- .trim: strip leading/trailing whitespace -->
  <input v-model.trim="text" />

  <!-- .number: cast to Number (NaN if invalid) -->
  <input v-model.number="age" type="number" />
</template>

Checkbox et radio

Une checkbox unique se lie à un booléen (cochée = true). Plusieurs checkboxes partageant le même v-model se lient à un tableau de leurs attributs value — cocher ajoute la valeur, décocher la retire. Les radios partageant un v-model lient la valeur de l'option choisie à la ref. Utilisez les attributs true-value / false-value pour personnaliser le mapping booléen.

vue3
<script setup>
import { ref } from 'vue'
const agreed = ref(false)
const fruits = ref([])     // array for multi-checkbox
const picked = ref('')     // string for radio
</script>

<template>
  <!-- single checkbox -> boolean -->
  <input type="checkbox" v-model="agreed" /> I agree

  <!-- multiple checkboxes with same v-model -> array -->
  <input type="checkbox" value="apple" v-model="fruits" /> Apple
  <input type="checkbox" value="banana" v-model="fruits" /> Banana
  <input type="checkbox" value="cherry" v-model="fruits" /> Cherry
  <p>Selected: {{ fruits }}</p>

  <!-- radio: value binds to the chosen option -->
  <input type="radio" value="A" v-model="picked" /> A
  <input type="radio" value="B" v-model="picked" /> B
</template>

Select

Sur <select>, v-model va sur l'élément select (pas les options) et se synchronise avec la valeur de l'option choisie. Utilisez une option placeholder désactivée avec valeur vide pour l'UX « veuillez choisir ». Pour des options dynamiques, rendez-les avec v-for et liez :value. Ajoutez l'attribut multiple pour permettre la multi-sélection — v-model se lie alors à un tableau des valeurs sélectionnées.

vue3
<script setup>
import { ref } from 'vue'
const selected = ref('')
const multi = ref([])

const options = [
  { value: 'a', label: 'Option A' },
  { value: 'b', label: 'Option B' }
]
</script>

<template>
  <!-- single select -->
  <select v-model="selected">
    <option disabled value="">Please select</option>
    <option value="a">A</option>
    <option value="b">B</option>
  </select>

  <!-- dynamic options -->
  <select v-model="selected">
    <option v-for="opt in options" :key="opt.value" :value="opt.value">
      {{ opt.label }}
    </option>
  </select>

  <!-- multi-select (hold Ctrl/Cmd) -> array -->
  <select v-model="multi" multiple>
    <option value="x">X</option>
    <option value="y">Y</option>
  </select>
</template>

Soumission et validation de formulaire

Utilisez @submit.prevent pour gérer la soumission du formulaire en prévenant le rechargement de page par défaut. Les objets de formulaire réactifs groupent les champs liés. Pour la validation, des bibliothèques comme VeeValidate ou Zod + un composable sont populaires pour les formulaires complexes, mais une simple fonction validate() retournant un objet d'erreurs marche bien pour les petits formulaires. Empêchez toujours le défaut pour permettre des soumissions style SPA.

vue3
<script setup>
import { reactive, ref } from 'vue'

const form = reactive({
  email: '',
  password: ''
})
const errors = ref({})

function validate() {
  errors.value = {}
  if (!form.email.includes('@')) errors.value.email = 'Invalid email'
  if (form.password.length < 6) errors.value.password = 'Too short'
  return Object.keys(errors.value).length === 0
}

function onSubmit() {
  if (!validate()) return
  // submit form...
}
</script>

<template>
  <form @submit.prevent="onSubmit">
    <input v-model.trim="form.email" />
    <span v-if="errors.email">{{ errors.email }}</span>

    <input type="password" v-model="form.password" />
    <span v-if="errors.password">{{ errors.password }}</span>

    <button type="submit">Submit</button>
  </form>
</template>

v-model avec composants custom

Enveloppez les champs de formulaire dans des composants custom pour la réutilisation. defineModel() retourne une ref qui lit la valeur du parent et réécrit via l'émission 'update:modelValue'. Le composant lie :value au modèle et @input le met à jour. Ce pattern permet de bâtir un design system cohérent d'inputs de formulaire (BaseInput, BaseSelect, BaseCheckbox) utilisables avec v-model comme les éléments natifs.

vue3
<!-- BaseInput.vue -->
<script setup>
const model = defineModel()

defineProps({
  label: String,
  type: { type: String, default: 'text' }
})
</script>

<template>
  <label>
    {{ label }}
    <input
      :type="type"
      :value="model"
      @input="model = $event.target.value"
    />
  </label>
</template>

<!-- Usage -->
<template>
  <BaseInput v-model="email" label="Email" type="email" />
</template>
10

Composants

Définir et utiliser des composants

Un composant est un fichier .vue avec template, script et style optionnel. Importez-le (auto-enregistré localement dans <script setup>) et utilisez-le comme tag HTML custom. Les noms de composants sont PascalCase dans le script et peuvent être kebab-case (mon-bouton) dans les templates — Vue les normalise. Les composants enregistrés globalement (app.component) sont disponibles partout sans import.

vue3
<!-- MyButton.vue -->
<template>
  <button class="btn"><slot /></button>
</template>

<!-- App.vue -->
<script setup>
import MyButton from './MyButton.vue'
</script>

<template>
  <MyButton>Click me</MyButton>
</template>

Composants dynamiques

<component :is='...'> rend un composant dynamiquement — la valeur peut être une chaîne de nom enregistré, un objet composant importé, ou un defineAsyncComponent. Enveloppez-le dans <keep-alive> pour préserver l'état du composant (saisie de formulaire, position de scroll) en basculant entre onglets. Utilisez shallowRef (pas ref) pour les objets composant afin d'éviter l'overhead de réactivité profonde.

vue3
<script setup>
import { ref, shallowRef } from 'vue'
import HomeTab from './HomeTab.vue'
import PostsTab from './PostsTab.vue'
import ArchiveTab from './ArchiveTab.vue'

const tabs = { HomeTab, PostsTab, ArchiveTab }
const current = shallowRef('HomeTab')

// keep component state when switching (e.g. form input)
import { keep-alive } from 'vue' // not real — use the tag
</script>

<template>
  <button v-for="(comp, name) in tabs" :key="name" @click="current = name">
    {{ name }}
  </button>

  <keep-alive>
    <component :is="tabs[current]" />
  </keep-alive>
</template>

Composants asynchrones

defineAsyncComponent charge paresseusement un composant au premier rendu — le chunk se fetch à la demande, réduisant la taille initiale du bundle. Configurez les états loading/error pour une UX douce. Combinez à Suspense pour coordonner plusieurs composants async. Le loader retourne une Promise du module composant (Vite/Webpack scinde automatiquement selon le dynamic import()).

vue3
<script setup>
import { defineAsyncComponent } from 'vue'

// lazy-load on first use (code-split)
const HeavyChart = defineAsyncComponent(() =>
  import('./HeavyChart.vue')
)

// with loading, error, delay, timeout states
const AdminPanel = defineAsyncComponent({
  loader: () => import('./AdminPanel.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorMsg,
  delay: 200,        // show loading after 200ms
  timeout: 5000      // error if not loaded in 5s
})
</script>

<template>
  <HeavyChart />
  <AdminPanel />
</template>

v-model de composant (multiple)

Les modèles nommés laissent un seul composant exposer plusieurs liaisons bidirectionnelles. defineModel('nom') déclare chacun. Le parent utilise v-model:nom='...'. Parfait pour des composants de formulaire regroupant plusieurs champs (ex. un composant adresse avec rue, ville, code postal). Le v-model par défaut (sans nom) mappe à 'modelValue'.

vue3
<!-- UserForm.vue -->
<script setup>
const firstName = defineModel('firstName')
const lastName = defineModel('lastName')
</script>

<template>
  <input v-model="firstName" />
  <input v-model="lastName" />
</template>

<!-- Parent.vue -->
<template>
  <UserForm
    v-model:firstName="form.first"
    v-model:lastName="form.last"
  />
</template>

Composants récursifs et circulaires

Un composant peut se référencer par son nom de fichier (auto-auto-référence). Parfait pour les structures d'arbres (arborescences de fichiers, fils de commentaires, menus). Pour les références circulaires entre deux composants (A importe B, B importe A), utilisez defineAsyncComponent pour l'un des deux, ou importez dans beforeCreate. Vue gère les composants récursifs mais surveillez les boucles infinies — ayez toujours un cas de base (pas d'enfants).

vue3
<!-- TreeNode.vue -->
<script setup>
defineProps({
  node: Object
})

// a component can reference itself by its filename
// TreeNode.vue can use <TreeNode /> recursively
</script>

<template>
  <div>
    {{ node.label }}
    <ul v-if="node.children?.length">
      <li v-for="child in node.children" :key="child.id">
        <TreeNode :node="child" />
      </li>
    </ul>
  </div>
</template>
11

Props

Déclarer les props

defineProps déclare le contrat d'entrée d'un composant. La déclaration à l'exécution supporte type, default, required et validator. La déclaration basée sur les types de Vue 3 (TS seulement) donne la sûreté de type mais perd la validation à l'exécution (à utiliser avec volar + une bibliothèque de validation). Les défauts des objets/tableaux doivent utiliser une fonction factory : default: () => [].

vue3
<script setup>
// runtime declaration (validates types)
const props = defineProps({
  title: String,
  count: { type: Number, default: 0 },
  items: { type: Array, required: true },
  callback: { type: Function, default: () => {} },
  status: {
    type: String,
    validator: (v) => ['active', 'idle'].includes(v)
  }
})

// type-based declaration (TS only, no runtime validation)
const props2 = defineProps<{
  title: string
  count?: number
}>()
</script>

Nommage et passage des props

Les props devraient être camelCase en JS (greetingMessage) et kebab-case dans les templates (greeting-message) — le HTML est insensible à la casse donc le kebab-case est plus sûr. Vue convertit automatiquement entre les deux. Les props de chaînes statiques utilisent la syntaxe d'attribut simple ; les valeurs dynamiques :prop. Passez les nombres/booléens/objets toujours avec : pour éviter qu'ils soient traités comme des chaînes.

vue3
<!-- Child.vue -->
<script setup>
defineProps({
  greetingMessage: String,
  userId: Number
})
</script>

<!-- Parent.vue -->
<template>
  <!-- kebab-case in templates (HTML-friendly) -->
  <Child greeting-message="Hello" :user-id="42" />

  <!-- camelCase also works in SFC templates -->
  <Child greetingMessage="Hello" :userId="42" />
</template>

Flux de données unidirectionnel

Les props sont en lecture seule — ne les mutez jamais directement. Vue avertit en mode dev. Pour changer la valeur d'une prop, émettez un événement et laissez le parent la mettre à jour (flux unidirectionnel). Pour une copie de travail locale, initialisez une ref depuis la prop et synchronisez via watch. Le pattern bidirectionnel le plus propre est v-model avec defineModel, qui abstrait la danse émission-et-mise-à-jour.

vue3
<!-- BAD: mutating a prop -->
<script setup>
const props = defineProps(['count'])

function inc() {
  props.count++  // WARNING: don't mutate props!
}
</script>

<!-- GOOD: emit to parent, or use local copy -->
<script setup>
import { ref, watch } from 'vue'
const props = defineProps(['count'])
const emit = defineEmits(['update:count'])

// local copy that syncs with prop
const local = ref(props.count)
watch(() => props.count, v => local.value = v)

function inc() {
  local.value++
  emit('update:count', local.value)
}
</script>

Validation et défauts des props

Vue valide les props en mode dev et avertit en cas d'échec (pas en production). type accepte un constructeur (String, Number, Boolean, Array, Object, Function, Symbol) ou un tableau de ceux-ci. Les défauts d'Object et Array DOIVENT être des fonctions retournant une nouvelle instance — sinon tous les composants partageraient la même référence par défaut (bugs de mutation). Les validators tournent après les vérifications de type.

vue3
<script setup>
const props = defineProps({
  // type can be an array of allowed types
  value: { type: [String, Number], required: true },

  // object/array default MUST be a factory function
  list: {
    type: Array,
    default: () => []
  },

  // custom validator
  age: {
    type: Number,
    validator: (v) => v >= 0 && v <= 150
  },

  // multiple checks combined
  email: {
    type: String,
    required: true,
    validator: (v) => v.includes('@')
  }
})
</script>

Casting booléen et héritage d'attributs

Les props booléennes ont un casting spécial : la présence sans valeur signifie true. Le fallthrough d'attributs passe les attributs non-props (class, style, id, data-*) à l'élément racine automatiquement. Les racines multiples exigent un v-bind='$attrs' explicite sur l'élément voulu. Désactivez le fallthrough avec defineOptions({ inheritAttrs: false }) pour un contrôle total.

vue3
<!-- prop declared as Boolean -->
<script setup>
defineProps({
  disabled: Boolean,
  active: Boolean
})
</script>

<!-- Parent -->
<template>
  <MyButton disabled />       <!-- disabled = true -->
  <MyButton :disabled="false" /> <!-- disabled = false -->
  <MyButton />                <!-- disabled = undefined -->
</template>

<!-- Attribute fallthrough: non-prop attributes
     land on the root element automatically -->
<template>
  <!-- <MyButton data-id="5" class="large" /> -->
  <!-- the data-id and class merge onto the <button> root -->
  <button>...</button>
</template>
12

Emits

Déclarer et émettre

defineEmits déclare les événements qu'un composant peut émettre. La forme objet permet des validators qui reçoivent le payload et retournent false pour avertir (mode dev). Les emits remontent l'arbre — les parents écoutent avec @nom-evenement. Déclarez toujours les emits explicitement : cela documente l'API, permet d'exclure du fallthrough d'attributs et supporte la validation. emit() prend le nom de l'événement plus des args de payload optionnels.

vue3
<script setup>
// declare emits (with optional validation)
const emit = defineEmits({
  // null-ish = no validation
  click: null,

  // function = validate payload
  submit: (payload) => {
    if (!payload.email) {
      console.warn('submit needs email')
      return false
    }
    return true
  }
})

function handleSubmit() {
  emit('submit', { email: '[email protected]', name: 'Alice' })
}
</script>

Écouter les emits

Les parents écoutent avec @nom-evenement (ou v-on:nom-evenement). Le handler reçoit tout payload émis. Les fonctions fléchées inline sont pratiques pour les transformations simples (@increment='n => count += n'). Les handlers de méthode reçoivent automatiquement le payload en premier argument. Les événements DOM natifs sur l'élément racine d'un composant passent par le fallthrough sauf s'ils sont déclarés dans emits — déclarer 'click' en fait un événement custom à la place.

vue3
<!-- Child.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])

function click() {
  emit('increment', 5)
}
</script>

<template>
  <button @click="click">+5</button>
</template>

<!-- Parent.vue -->
<template>
  <!-- inline handler -->
  <Child @increment="n => count += n" />

  <!-- method handler -->
  <Child @increment="onIncrement" @delete="onDelete" />
</template>

<script setup>
function onIncrement(amount) {
  console.log('incremented by', amount)
}
</script>

Implémentation de v-model

v-model sur un composant est du sucre pour :modelValue + @update:modelValue. L'enfant reçoit la valeur via une prop modelValue et émet update:modelValue pour se synchroniser. C'est le pattern manuel ; defineModel() (Vue 3.4+) l'enveloppe. Pour un v-model nommé (v-model:foo), utilisez la prop nom foo et l'événement update:foo. Cela permet de bâtir des composants de formulaire marchant comme des inputs natifs.

vue3
<!-- CustomInput.vue (manual implementation) -->
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])

function onInput(e) {
  emit('update:modelValue', e.target.value)
}
</script>

<template>
  <input
    :value="modelValue"
    @input="onInput"
  />
</template>

<!-- Parent -->
<template>
  <CustomInput v-model="text" />
</template>

Validation des emits

Les validators d'emit reçoivent les args du payload et retournent false pour déclencher un avertissement en mode dev. Ils n'empêchent pas l'émission — ils avertissent seulement. Cela attrape tôt les violations de contrat pendant le développement. Utilisez-les pour documenter les shapes de payload attendues. En production, les validators sont retirés, donc ne vous y fiez pas pour la sécurité ou le flux de contrôle.

vue3
<script setup>
const emit = defineEmits({
  // no validation
  click: null,

  // validate payload; return false to warn
  change: (value) => {
    if (typeof value !== 'string') {
      console.warn('change payload must be string')
      return false
    }
    return true
  },

  // validate multiple args
  update: (id, value) => {
    if (!id || value === undefined) return false
    return true
  }
})

// validation runs on emit
emit('change', 123)  // warns: must be string
</script>

Événements vs props : quand utiliser

Suivez le flux de données unidirectionnel : props vers le bas, événements vers le haut. Pour la liaison bidirectionnelle, utilisez v-model (sucre props + emit). Pour une communication profondément imbriquée, le forage de props devient douloureux — utilisez provide/inject pour l'injection de dépendances ou un store (Pinia) pour l'état partagé. Les événements notifient « quelque chose s'est passé » ; les props fournissent « voici tes données ».

vue3
<!-- Parent-to-child: props (down) -->
<template>
  <Child :data="parentData" :config="config" />
</template>

<!-- Child-to-parent: emits (up) -->
<template>
  <Child @change="onChange" @submit="onSubmit" />
</template>

<!-- Two-way: v-model (combines both) -->
<template>
  <Child v-model="value" />
</template>

<!-- For complex state, prefer provide/inject or a store -->
13

Slots

Slot par défaut

Les slots laissent un parent injecter du contenu dans le template d'un composant enfant. L'élément <slot> est le placeholder. Le contenu enfant du parent remplit le slot par défaut. Les slots permettent la composition : Card gère le style de l'enveloppe, le parent contrôle le contenu interne. Sans slots, il faudrait une prop pour chaque élément interne possible — les slots sont bien plus flexibles.

vue3
<!-- Card.vue -->
<template>
  <div class="card">
    <slot />
  </div>
</template>

<!-- Usage -->
<template>
  <Card>
    <p>This goes into the default slot</p>
    <button>Action</button>
  </Card>
</template>

Slots nommés

Les slots nommés permettent à un composant d'avoir plusieurs placeholders de contenu. Déclarez avec <slot name='foo' />, remplissez avec <template #foo>. Le # est le raccourci de v-slot:. Le slot sans nom est le slot 'default' — le contenu sans enveloppe template y va. Les slots nommés sont parfaits pour les mises en page (header, sidebar, main, footer) où le parent remplit chaque région.

vue3
<!-- Layout.vue -->
<template>
  <header><slot name="header" /></header>
  <main><slot /></main>
  <footer><slot name="footer" /></footer>
</template>

<!-- Usage with # shorthand -->
<template>
  <Layout>
    <template #header>
      <h1>My Page Title</h1>
    </template>

    <!-- default slot (no #name) -->
    <p>Main content here</p>

    <template #footer>
      <p>© 2025</p>
    </template>
  </Layout>
</template>

Slot props (slots scopés)

Les slots scopés permettent à un enfant de renvoyer des données au contenu de slot du parent. L'enfant lie les données sur <slot :item='item'> ; le parent les reçoit via v-slot='{ item }' (ou #default='{ item }'). C'est le socle des composants de liste réutilisables (table de données, liste virtuelle) : l'enfant gère l'itération, le parent contrôle le rendu de chaque élément.

vue3
<!-- List.vue -->
<template>
  <ul>
    <li v-for="item in items" :key="item.id">
      <slot :item="item" :index="index" />
    </li>
  </ul>
</template>

<script setup>
defineProps(['items'])
</script>

<!-- Usage: receive slot props via v-slot -->
<template>
  <List :items="todos">
    <template #default="{ item, index }">
      <input type="checkbox" v-model="item.done" />
      <span :class="{ done: item.done }">{{ index }}: {{ item.text }}</span>
    </template>
  </List>
</template>

Contenu de slot par défaut

Le contenu de repli du slot va entre <slot> et </slot>. Il ne se rend que quand le parent ne fournit aucun contenu de slot. Génial pour des défauts sensés — un label de bouton, un message d'état vide, un placeholder. Si le parent passe même une chaîne vide, le repli est surchargé.

vue3
<!-- Button.vue -->
<template>
  <button>
    <slot>Click here</slot>  <!-- fallback content -->
  </button>
</template>

<!-- Usage -->
<template>
  <Button />             <!-- renders "Click here" -->
  <Button>Save</Button>  <!-- renders "Save" -->
</template>

Portée de rendu et usage des slots

Le contenu de slot se rend dans la portée du PARENT — il peut accéder à l'état du parent mais pas directement à celui de l'enfant (sauf via slot props). Cette séparation laisse l'enfant gérer la mécanique (pagination, virtualisation, fetch) pendant que le parent contrôle la présentation. Le pattern de slot scopé (FancyList + UserCard) est une technique de composition puissante — l'enfant possède le flux de données, le parent le rendu.

vue3
<!-- FancyList.vue (scoped slot pattern) -->
<script setup>
const props = defineProps(['items', 'pageSize'])
import { ref, computed } from 'vue'

const page = ref(1)
const paged = computed(() =>
  props.items.slice((page.value - 1) * props.pageSize, page.value * props.pageSize)
)
</script>

<template>
  <div v-for="item in paged" :key="item.id">
    <slot :item="item" :page="page" />
  </div>
</template>

<!-- Usage: parent fully controls rendering -->
<FancyList :items="users" :pageSize="10">
  <template #default="{ item, page }">
    <UserCard :user="item" />
    <small>Page {{ page }}</small>
  </template>
</FancyList>
14

Hooks de cycle de vie

Hooks de l'API Composition

Les hooks de cycle de vie tournent à des étapes précises. onMounted se déclenche après le rendu du DOM (sûr d'accéder aux éléments, lancer des libs canvas, fetcher des données). onUpdated après chaque mise à jour réactive — évitez de muter l'état ici (boucle infinie). onUnmounted pour le nettoyage (timers, listeners, abonnements). Les hooks doivent s'appeler synchrone dans setup, mais peuvent s'appeler plusieurs fois.

vue3
<script setup>
import {
  onBeforeMount, onMounted,
  onBeforeUpdate, onUpdated,
  onBeforeUnmount, onUnmounted,
  onActivated, onDeactivated,
  onErrorCaptured
} from 'vue'

onBeforeMount(() => console.log('before mount'))
onMounted(() => console.log('mounted — DOM ready'))
onBeforeUpdate(() => console.log('before re-render'))
onUpdated(() => console.log('after re-render'))
onBeforeUnmount(() => console.log('before unmount'))
onUnmounted(() => console.log('unmounted — cleanup'))
</script>

Setup vs created

Dans <script setup>, tout le corps du script tourne pendant l'initialisation du composant — équivalent à beforeCreate + created dans l'API Options. Pas de hook created() séparé. Le code de premier niveau (déclarations, appels de fonctions, même travail async) tourne une fois par instance. Pour le fetch de données, c'est un endroit courant pour commencer (bien que onMounted convienne aussi — le fetch démarre pareil).

vue3
<script setup>
// <script setup> runs BEFORE the component is mounted
// (equivalent to beforeCreate + created in Options API)

import { ref } from 'vue'

// this code runs once per component instance,
// before reactive state is exposed to the template
const count = ref(0)
console.log('component created, count =', count.value)

// no need for created() hook — just run code here
fetch('/api/data')
  .then(r => r.json())
  .then(data => { /* ... */ })
</script>

Mounted et nettoyage

Les paires setup/nettoyage sont essentielles : tout listener, timer, abonnement ou observateur ajouté dans onMounted DOIT être retiré dans onUnmounted. Ne pas nettoyer cause des fuites mémoire et des handlers zombies se déclenchant sur des composants détruits. Le pattern : addEventListener dans onMounted, removeEventListener dans onUnmounted. Pour les watchers, utilisez la fonction stop retournée ou ils s'auto-nettoient au démontage.

vue3
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const windowWidth = ref(window.innerWidth)

function onResize() {
  windowWidth.value = window.innerWidth
}

onMounted(() => {
  // setup side effects after DOM is ready
  window.addEventListener('resize', onResize)
  console.log('mounted')
})

onUnmounted(() => {
  // ALWAYS clean up to avoid memory leaks
  window.removeEventListener('resize', onResize)
})
</script>

Hooks KeepAlive

Quand un composant est enveloppé dans <KeepAlive>, s'en éloigner ne le démonte pas — il est désactivé (mis en cache). onActivated et onDeactivated se déclenchent à l'affichage/masquage. Utilisez-les pour pauser/reprendre le travail (polling, lecture vidéo) sans setup/démontage complets. onMounted se déclenche quand même une fois (première activation) ; onUnmounted ne se déclenche jamais tant que caché. Ces hooks optimisent l'usage des ressources pour les onglets cachés.

vue3
<script setup>
import { onActivated, onDeactivated } from 'vue'

// these fire when the component is wrapped in <KeepAlive>
// and is being shown (activated) or hidden (deactivated)
onActivated(() => {
  console.log('component shown again — resume polling')
  startPolling()
})

onDeactivated(() => {
  console.log('component hidden but not unmounted — pause')
  stopPolling()
})

// onMounted fires only once (first show)
// onActivated fires every time it's re-shown
</script>

Error Captured

onErrorCaptured attrape les erreurs des composants descendants (dans les templates, rendu, cycle de vie, watchers). Il reçoit (erreur, instance, info). Retournez false pour arrêter la propagation de l'erreur aux handlers errorCaptured parents et au errorHandler global. À utiliser pour des composants frontière gérant gracieusement les erreurs enfants (comme les Error Boundaries de React). Combinez à Suspense pour les états d'erreur async.

vue3
<script setup>
import { onErrorCaptured, ref } from 'vue'

const error = ref(null)

onErrorCaptured((err, instance, info) => {
  // err: the error thrown
  // instance: component that threw
  // info: lifecycle hook or event name where it occurred
  error.value = err.message
  console.error('Captured:', err, info)

  // return false to stop propagation to parent
  return false
})
</script>

<template>
  <div v-if="error" class="error">{{ error }}</div>
  <slot v-else />
</template>
15

API Composition

ref vs reactive

ref() marche avec toute valeur (primitifs, objets). L'accès réactif exige .value en JS, mais auto-déballe dans les templates. reactive() ne marche que sur objets/tableaux — pas de .value requis. Utilisez ref pour les primitifs et les valeurs remplaçables ; reactive pour l'état groupé. Règle empirique : préférez ref() pour les valeurs individuelles, reactive() pour les objets d'état. Mélanger va bien — les refs auto-déballent dans les objets réactifs.

vue3
<script setup>
import { ref, reactive } from 'vue'

// ref: works with any value, access via .value
const count = ref(0)
count.value++
console.log(count.value)  // 1

// reactive: only for objects/arrays, no .value needed
const state = reactive({ count: 0, user: { name: 'A' } })
state.count++
console.log(state.count)  // 1

// refs auto-unwrap in templates and reactive objects
const wrapper = reactive({ count })  // wrapper.count === count.value
</script>

Pièges de reactive

Les objets réactifs ont deux pièges : on ne peut pas réaffecter la variable (state = newObj) — mutez les propriétés à la place (state.list = []). Le déstructurage perd la réactivité car la variable déstructurée est un snapshot. Utilisez toRefs() pour convertir les propriétés réactives en refs restant liées. Ces pièges expliquent pourquoi beaucoup de devs préfèrent ref() — remplaçable (réglez .value) et friendly au déstructurage.

vue3
<script setup>
import { reactive, ref } from 'vue'

const state = reactive({ list: [1, 2, 3] })

// PITFALL 1: replacing the whole object loses reactivity
// state = reactive({ list: [4, 5] })  // ERROR: reassign

// GOOD: mutate properties
state.list = [4, 5]

// PITFALL 2: destructuring loses reactivity
let { list } = state  // 'list' is now plain
// list.push(4) won't trigger updates

// FIX: use toRefs to keep reactivity
import { toRefs } from 'vue'
const { list } = toRefs(state)  // now list is a ref
</script>

toRef et toRefs

toRef() convertit une seule propriété réactive en ref restant liée (muter l'une affecte l'autre). toRefs() convertit TOUTES les propriétés — utile pour retourner un état réactif depuis des composables en préservant le déstructurage. Sans toRefs, les valeurs déstructurées perdent la réactivité. Pattern : le composable retourne toRefs(state) pour que les consommateurs puissent déstructurer sans casser la réactivité.

vue3
<script setup>
import { reactive, toRef, toRefs } from 'vue'

const state = reactive({
  count: 0,
  name: 'Alice'
})

// toRef: single property -> ref (stays linked to state)
const countRef = toRef(state, 'count')

// toRefs: all properties -> object of refs
const { count, name } = toRefs(state)

countRef.value++      // updates state.count
count.value++         // also updates state.count
console.log(state.count)  // 2
</script>

computed et watch dans Setup

Dans <script setup>, computed() et watch() s'importent et s'appellent directement. computed crée une ref dérivée ; watch exécute un callback au changement de source. watch peut prendre une ref unique, un getter, un tableau de sources ou un objet réactif. Ce sont les primitives cœur de l'API Composition — combinez-les pour encapsuler la logique dans des composables.

vue3
<script setup>
import { ref, computed, watch } from 'vue'

const a = ref(1)
const b = ref(2)

// computed: derived value, cached
const sum = computed(() => a.value + b.value)

// watch: side effect on change
watch(sum, (newSum) => {
  console.log('sum changed to', newSum)
})

// watch multiple sources
watch([a, b], ([newA, newB]) => {
  console.log('a or b changed:', newA, newB)
})
</script>

shallowRef et shallowReactive

shallowRef et shallowReactive renoncent à la réactivité profonde — seuls la référence/les propriétés de premier niveau sont suivis. Cela améliore drastiquement la performance pour les grandes structures de données (ex. le tableau de données d'un graphique, un graphe de scène 3D) où le suivi profond est du gaspillage. Utilisez triggerRef() pour notifier manuellement Vue après une mutation profonde. N'y recourez qu'après avoir mesuré un souci de perf.

vue3
<script setup>
import { shallowRef, shallowReactive, triggerRef } from 'vue'

// shallowRef: only .value changes trigger updates
// (deep changes to .value properties do NOT)
const big = shallowRef({ items: [1, 2, 3] })
big.value.items.push(4)       // NO update triggered
big.value = { items: [1,2,3,4] }  // update triggered

// force update after deep mutation
big.value.items.push(5)
triggerRef(big)  // tells Vue to re-render

// shallowReactive: only root-level props are reactive
const state = shallowReactive({ user: { name: 'A' } })
state.count = 1            // reactive
state.user.name = 'B'      // NOT reactive
</script>
16

Composables

Écrire un composable

Un composable est une fonction qui encapsule de la logique réactive réutilisable. Par convention, nommez-le useQuelqueChose. Il utilise les hooks de l'API Composition (onMounted, etc.) qui se lient au cycle de vie du composant consommateur. Retournez des refs et des méthodes. Le composant les déstructure. Les composables sont l'équivalent Vue des hooks React — ils permettent de partager de la logique avec état sans render props ni HOC.

vue3
<!-- useMousePosition.js -->
import { ref, onMounted, onUnmounted } from 'vue'

export function useMousePosition() {
  const x = ref(0)
  const y = ref(0)

  function update(e) {
    x.value = e.pageX
    y.value = e.pageY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  return { x, y }
}

<!-- In component -->
<script setup>
import { useMousePosition } from './useMousePosition'
const { x, y } = useMousePosition()
</script>

Composable avec état (état partagé)

Quand l'état se déclare à la portée du module (hors de la fonction), c'est un singleton — tous les composants utilisant le composable partagent le même état. Une alternative légère à Pinia pour un état global simple. Utilisez readonly() pour exposer l'état sans permettre la mutation directe — les composants doivent appeler login/logout pour le changer. Pour des apps complexes, préférez Pinia (meilleurs devtools, persistance, support SSR).

vue3
<!-- useUser.js -->
import { reactive, readonly } from 'vue'

// module-scoped state — shared across all consumers
const state = reactive({
  user: null,
  loading: false
})

export function useUser() {
  async function login(credentials) {
    state.loading = true
    state.user = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify(credentials)
    }).then(r => r.json())
    state.loading = false
  }

  function logout() {
    state.user = null
  }

  return {
    user: readonly(state.user),  // expose read-only
    loading: readonly(state.loading),
    login,
    logout
  }
}

Composable useFetch

Ce composable enveloppe fetch avec états loading/error et re-fetch quand une url réactive change. isRef() vérifie si l'entrée est une ref ; unref() la déballe (retourne la valeur pour les refs, identité sinon). Retourner refresh laisse le consommateur re-fetcher manuellement. Ce pattern (entrée réactive + re-run automatique + exposition d'état) est le pain quotidien des composables de fetch de données.

vue3
<!-- useFetch.js -->
import { ref, watchEffect, isRef, unref } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)
  const loading = ref(true)

  async function doFetch() {
    loading.value = true
    error.value = null
    try {
      const res = await fetch(unref(url))
      if (!res.ok) throw new Error('HTTP ' + res.status)
      data.value = await res.json()
    } catch (e) {
      error.value = e.message
    } finally {
      loading.value = false
    }
  }

  // re-fetch when url ref changes
  if (isRef(url)) {
    watchEffect(doFetch)
  } else {
    doFetch()
  }

  return { data, error, loading, refresh: doFetch }
}

Composable avec nettoyage

Les composables qui enregistrent des effets de bord (listeners, timers, abonnements) DOIVENT nettoyer — typiquement via onUnmounted dans le composable. Cela lie le nettoyage à tout composant consommant le composable, donc le consommateur n'a pas à s'en souvenir. Un avantage majeur des composables face aux fonctions utilitaires : ils participent au cycle de vie du composant.

vue3
<!-- useEventListener.js -->
import { onUnmounted } from 'vue'

export function useEventListener(target, event, callback) {
  target.addEventListener(event, callback)

  // auto-cleanup when the consuming component unmounts
  onUnmounted(() => {
    target.removeEventListener(event, callback)
  })
}

<!-- Usage -->
<script setup>
import { useEventListener } from './useEventListener'
import { ref } from 'vue'

const key = ref('')
useEventListener(window, 'keydown', (e) => {
  key.value = e.key
})
// listener is removed automatically on unmount
</script>

Conventions des composables

Suivez ces conventions : (1) nommez les composables avec le préfixe use ; (2) retournez des refs (pas des valeurs simples — elles perdent la réactivité) ; (3) acceptez des refs ou getters en entrées pour la flexibilité ; (4) utilisez onUnmounted pour le nettoyage ; (5) gardez-les focalisés (une préoccupation par composable). Ces conventions rendent les composables composables entre eux et prévisibles à l'usage.

vue3
<!-- DO: name with 'use' prefix, return refs -->
export function useCounter(initial = 0) {
  const count = ref(initial)
  const inc = () => count.value++
  const dec = () => count.value--
  return { count, inc, dec }
}

<!-- AVOID: returning plain values (loses reactivity) -->
export function badCounter() {
  let count = 0  // plain variable — NOT reactive!
  return { count, inc: () => count++ }
}

<!-- DO: accept refs/getters for flexible inputs -->
export function useSearch(query) {
  // query can be a ref, a getter, or a plain value
  return watchEffect(() => fetch('/api?q=' + unref(query)))
}
17

Réactivité en profondeur

Mécanique des Proxy réactifs

La réactivité de Vue 3 utilise Proxy (ES6). reactive() retourne un Proxy qui intercepte get (pour suivre les dépendances) et set (pour déclencher les mises à jour). L'objet original n'est pas modifié — on obtient une version enveloppée. isReactive() vérifie si quelque chose est un proxy réactif. Plus puissant que l'approche Object.defineProperty de Vue 2, qui ne pouvait pas détecter l'ajout de nouvelles propriétés.

vue3
<script setup>
import { reactive, isReactive, isProxy } from 'vue'

const state = reactive({ count: 0 })

// reactive() wraps the object in a Proxy
// reads/writes are tracked and trigger updates
state.count++  // triggers re-render

// the original object is NOT reactive
const raw = { count: 0 }
const wrapped = reactive(raw)
console.log(raw === wrapped)         // false
console.log(isReactive(wrapped))     // true
console.log(isReactive(raw))         // false
console.log(isProxy(wrapped))        // true
</script>

Règles de déballage des refs

Règles de déballage des refs : dans <script>, accès via .value ; dans les templates et dans les objets réactifs, les refs auto-déballent vers leur .value. Voilà pourquoi {{ count }} marche dans un template sans .value. Le déballage automatique est superficiel — les refs imbriquées dans tableaux/Maps ne déballent pas. Les objets réactifs contenant des refs mutent la valeur de la ref à l'affectation : state.count = 5 règle count.value = 5.

vue3
<script setup>
import { ref, reactive } from 'vue'

const count = ref(0)
const state = reactive({ count })

// in JS: ref needs .value
count.value = 1

// in reactive object: ref auto-unwraps
console.log(state.count)  // 1 (not count.value)
state.count = 5           // updates count.value

// in templates: ref auto-unwraps
// {{ count }} renders count.value
</script>

<template>
  <p>{{ count }}</p>  <!-- 5, not [object Object] -->
</template>

Effect et track/trigger (internals)

effect() est la primitive bas niveau derrière la réactivité — elle exécute une fonction, suit toute lecture réactive à l'intérieur, et ré-tourne quand une valeur suivie change. computed, watch, watchEffect et le rendu des composants s'appuient tous sur effect. On appelle rarement effect() directement dans le code d'app — préférez computed/watch/watchEffect — mais c'est le moteur. Le comprendre aide à raisonner sur le réordonnancement et le timing.

vue3
<script setup>
import { ref, effect } from 'vue'

const count = ref(0)

// effect runs immediately, then re-runs on dep change
effect(() => {
  console.log('count is', count.value)
})
// logs: count is 0

count.value = 10
// logs: count is 10

// internally:
// - effect tracks dependencies accessed inside it
// - setting count.value triggers all tracked effects
</script>

markRaw et readonly

markRaw() retire définitivement un objet de la réactivité — utile pour les instances de classes tierces (graphiques, cartes, état de jeu) qui ont leurs propres mécanismes de mise à jour et ne doivent pas s'envelopper en Proxy. readonly() crée une vue en lecture seule d'un objet réactif — les tentatives de mutation avertissent en mode dev. Utilisez readonly pour exposer l'état depuis composables/stores en prévenant la mutation directe.

vue3
<script setup>
import { reactive, markRaw, readonly, isReadonly } from 'vue'

// markRaw: opt a value OUT of reactivity forever
const bigChart = markRaw(new HeavyChartLib())
const state = reactive({ chart: bigChart })
// state.chart mutations won't trigger Vue updates
// (use chart's own API to update it)

// readonly: make a reactive object read-only
const original = reactive({ count: 0 })
const frozen = readonly(original)
frozen.count = 5
// warning: target is readonly (dev mode)

console.log(isReadonly(frozen))  // true
</script>

Ref personnalisée (factory)

customRef() permet de contrôler explicitement le suivi des dépendances et le déclenchement. La factory reçoit track() et trigger() — appelez track() dans get() pour enregistrer la dépendance, appelez trigger() dans set() pour notifier les mises à jour. Cela permet des patterns comme des refs débouncées, des refs paresseuses ou des refs adossées au stockage. Puissant mais avec parcimonie — habituellement watchEffect + une ref normale est plus clair.

vue3
<script setup>
import { customRef } from 'vue'

// debounce a ref's updates
function debouncedRef(value, delay = 200) {
  let timeout
  return customRef((track, trigger) => ({
    get() {
      track()  // tell Vue this value is a dependency
      return value
    },
    set(newValue) {
      clearTimeout(timeout)
      timeout = setTimeout(() => {
        value = newValue
        trigger()  // notify Vue of the change
      }, delay)
    }
  }))
}

const text = debouncedRef('', 300)
// input only triggers re-render 300ms after typing stops
</script>
18

Vue Router

Mise en place du Router

createRouter met en place le routage. createWebHistory utilise le mode history HTML5 (URLs propres, exige un repli serveur vers index.html). Chargez paresseusement les composants de routes avec le dynamic import() pour le code-splitting — chaque route devient son propre bundle. Les segments dynamiques (:id) s'accèdent via route.params. Installez le router comme plugin avec app.use(router).

vue3
<!-- router/index.js -->
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  { path: '/', name: 'home', component: Home },
  {
    path: '/about',
    name: 'about',
    // lazy-load for code-splitting
    component: () => import('../views/About.vue')
  },
  { path: '/user/:id', name: 'user', component: () => import('../views/User.vue') }
]

export const router = createRouter({
  history: createWebHistory(),
  routes
})

<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'
import { router } from './router'

createApp(App).use(router).mount('#app')

RouterView et RouterLink

<RouterView> est le placeholder où le composant de la route matchée se rend. <RouterLink> rend un tag <a> mais intercepte les clics pour une navigation côté client (pas de rechargement complet de page). La prop to accepte un chemin de chaîne ou un objet ({ name, params, query }). RouterLink ajoute les classes active/exact-active pour styler le lien courant.

vue3
<!-- App.vue -->
<template>
  <nav>
    <!-- RouterLink renders <a>, handles navigation -->
    <RouterLink to="/">Home</RouterLink>
    <RouterLink to="/about">About</RouterLink>
    <RouterLink :to="{ name: 'user', params: { id: 42 } }">
      User 42
    </RouterLink>
  </nav>

  <!-- matched route's component renders here -->
  <RouterView />
</template>

Navigation et routage programmatique

useRouter() donne l'instance du router pour la navigation ; useRoute() la route courante (réactive). push ajoute une entrée d'historique (le bouton retour marche) ; replace non. Les propriétés de route (path, params, query, hash, name, matched) sont réactives — watchers et computed ré-tournent à la navigation. Utilisez toujours router.push pour la navigation dans l'app — jamais window.location pour rester en SPA.

vue3
<script setup>
import { useRouter, useRoute } from 'vue-router'

const router = useRouter()
const route = useRoute()

// push to a new URL (adds to history)
function goHome() {
  router.push('/')
  router.push({ name: 'user', params: { id: 1 } })
  router.push({ path: '/search', query: { q: 'vue' } })
}

// replace current entry (no back button)
router.replace('/login')

// go back/forward
router.back()
router.forward()
router.go(-2)

// access current route info
console.log(route.path, route.params.id, route.query.q)
</script>

Gardes de route

Les gardes contrôlent le flux de navigation. Le beforeEach global est génial pour les vérifications d'auth. Le beforeEnter par route garde des routes précises. Les gardes dans le composant (onBeforeRouteLeave, onBeforeRouteUpdate) sont utiles pour les avertissements de changements non sauvegardés. Retournez false ou une route pour annuler/rediriger ; true/undefined pour confirmer. Les gardes async peuvent retourner une Promise. Utilisez route.meta pour attacher des flags comme requiresAuth.

vue3
<!-- router/index.js -->
const router = createRouter({ history, routes })

// global guard: runs on every navigation
router.beforeEach((to, from) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    return '/login'  // redirect
  }
  // return true or undefined to confirm
})

// per-route guard
{ path: '/admin', component: Admin, beforeEnter: (to, from) => {
  if (!isAdmin()) return '/403'
}}

// in-component guard
<script setup>
import { onBeforeRouteLeave } from 'vue-router'
onBeforeRouteLeave((to, from) => {
  if (hasUnsavedChanges()) {
    return confirm('Discard changes?')
  }
})
</script>

Chargement paresseux et routes imbriquées

Les routes imbriquées rendent les composants enfants dans le <RouterView> du parent. Définissez les children avec des chemins relatifs au parent. Le chemin vide ('') matche exactement l'URL du parent. Le dynamic import() scinde chaque route en son propre bundle. Utilisez route.meta pour attacher des données (exigences d'auth, titres) — accessibles dans les gardes via to.meta. Regroupez les routes liées avec un commentaire de nom de chunk.

vue3
const routes = [
  {
    path: '/dashboard',
    component: () => import('../views/Dashboard.vue'),
    children: [
      { path: '', component: () => import('../views/Overview.vue') },
      { path: 'stats', component: () => import('../views/Stats.vue') },
      { path: 'settings', component: () => import('../views/Settings.vue') }
    ]
  },
  // group routes into one chunk
  {
    path: '/admin',
    component: () => import(/* webpackChunkName: "admin" */ '../views/Admin.vue'),
    meta: { requiresAuth: true, role: 'admin' }
  }
]
19

Gestion d'état (Pinia)

Définir un store

Pinia est la gestion d'état officielle de Vue (successeur de Vuex). defineStore avec une fonction setup donne la syntaxe de l'API Composition — ref/computed sont state/getters, les fonctions retournées sont des actions. Le premier argument est un id de store unique. Les setup stores sont flexibles (on peut utiliser n'importe quel composable dedans). Alternativement, utilisez la syntaxe Options (objet state/getters/actions) pour un feeling plus proche de Vuex.

vue3
<!-- stores/counter.js -->
import { defineStore } from 'pinia'

// setup syntax (composition API style)
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const double = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  function asyncIncrement() {
    setTimeout(() => count.value++, 1000)
  }

  return { count, double, increment, asyncIncrement }
})

Utiliser un store

Appelez useStore() dans setup pour accéder à un store. Pour le déstructurage réactif, utilisez storeToRefs() (comme toRefs mais saute les actions). Les actions peuvent se déstructurer directement — elles sont liées au store. Pinia autorise la mutation directe (counter.count = 5) et $patch pour les mises à jour en lot. Les stores sont des singletons — la même instance à travers tous les composants. Installez Pinia avec app.use(createPinia()).

vue3
<script setup>
import { useCounterStore } from '../stores/counter'
import { storeToRefs } from 'pinia'

const counter = useCounterStore()

// state and getters lose reactivity if destructured directly
// use storeToRefs to preserve it
const { count, double } = storeToRefs(counter)

// actions can be destructured directly (they're functions)
const { increment } = counter

// mutate state directly (Pinia allows it, unlike Vuex)
counter.count = 5
counter.$patch({ count: 10 })
counter.$patch(state => { state.count++ })
</script>

<template>
  <p>{{ count }} x 2 = {{ double }}</p>
  <button @click="increment">+</button>
</template>

Getters et composition de stores

Les getters sont des valeurs calculées dérivées de l'état. Pour utiliser un autre store à l'intérieur, appelez simplement son useStore() — Pinia gère la dépendance. Cela rend la composition de stores triviale (contrairement aux modules Vuex). Les getters peuvent aussi référencer d'autres getters. Pour les opérations async, écrivez simplement des fonctions async dans le store — pas de contexte 'actions' spécial comme Vuex.

vue3
<!-- stores/cart.js -->
import { defineStore } from 'pinia'
import { useUserStore } from './user'

export const useCartStore = defineStore('cart', () => {
  const items = ref([])

  // getter (computed)
  const total = computed(() =>
    items.value.reduce((sum, i) => sum + i.price * i.qty, 0)
  )

  const itemCount = computed(() =>
    items.value.reduce((n, i) => n + i.qty, 0)
  )

  // compose other stores
  const userStore = useUserStore()
  const canCheckout = computed(() =>
    userStore.isLoggedIn && items.value.length > 0
  )

  function addItem(item) {
    items.value.push(item)
  }

  return { items, total, itemCount, canCheckout, addItem }
})

Abonnements et persistance

$subscribe se déclenche à tout changement d'état (avec les infos de mutation et le nouvel état). À utiliser pour la persistance (localStorage, sessionStorage) ou la sync vers des systèmes externes. $onAction s'accroche aux appels d'actions — utile pour le logging, l'analytique ou mesurer la durée des actions. Les callbacks after/onError permettent de réagir à l'achèvement ou l'échec d'une action. Le nettoyage s'effectue automatiquement au démontage du composant.

vue3
<script setup>
import { useCartStore } from '../stores/cart'

const cart = useCartStore()

// subscribe to any state change
cart.$subscribe((mutation, state) => {
  console.log('cart changed', mutation.type, state)
  // persist to localStorage
  localStorage.setItem('cart', JSON.stringify(state.items))
})

// subscribe to actions
cart.$onAction(({ name, after, onError }) => {
  console.log('action started:', name)
  after(result => console.log('action done:', name, result))
  onError(err => console.error('action failed:', name, err))
})
</script>

Reset et modules de store

Les stores en syntaxe Options ont un $reset() intégré ; les setup stores non — implémentez reset() manuellement en réaffectant chaque ref. Pinia est modulaire par conception — chaque store est indépendant, pas de modules imbriqués comme Vuex. Composez les stores en appelant useOtherStore() à l'intérieur. Installez Pinia globalement avec createPinia(). Les stores sont tree-shakables et ont un excellent support TypeScript et d'intégration devtools.

vue3
<!-- stores/user.js -->
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', () => {
  const name = ref('')
  const isLoggedIn = ref(false)

  function login(n) { name.value = n; isLoggedIn.value = true }
  function logout() { name.value = ''; isLoggedIn.value = false }

  // Pinia setup stores don't have a built-in $reset
  // implement it manually
  function reset() {
    name.value = ''
    isLoggedIn.value = false
  }

  return { name, isLoggedIn, login, logout, reset }
})

<!-- main.js -->
import { createPinia } from 'pinia'
const pinia = createPinia()
app.use(pinia)
20

Transitions et animation

Composant Transition

Enveloppez un élément v-if/v-show dans <Transition> pour animer entrée/sortie. Vue ajoute 6 classes aux bons moments : *-enter-from (état initial), *-enter-active (pendant la transition), *-enter-to (état final), et *-leave-*. Définissez des transitions/animations CSS sur ces classes. La prop name remplace le préfixe 'v-'. Un seul élément enfant autorisé ; pour les listes utilisez TransitionGroup.

vue3
<template>
  <Transition name="fade">
    <p v-if="show">Hello</p>
  </Transition>
</template>

<style>
/* 6 classes: {name}-enter-{from,active,to}, {name}-leave-{...} */
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s ease;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>

Modes et hooks de Transition

mode='out-in' anime entièrement la sortie de l'élément partant avant que l'entrant ne commence — parfait pour échanger des composants (onglets) sans chevauchement. mode='in-out' est rarement utilisé. Les hooks JavaScript (@before-enter, @enter, @leave) permettent de piloter les animations avec des bibliothèques comme GSAP. Réglez :css='false' pour dire à Vue de sauter la détection CSS et ne s'appuyer que sur vos hooks JS (petit gain de perf).

vue3
<template>
  <!-- 'out-in': current leaves, then new enters -->
  <Transition mode="out-in" name="fade">
    <component :is="currentTab" />
  </Transition>

  <!-- JavaScript hooks for GSAP/anime.js -->
  <Transition
    @before-enter="beforeEnter"
    @enter="enter"
    @leave="leave"
    :css="false"
  >
    <div v-if="show">Animated</div>
  </Transition>
</template>

TransitionGroup pour les listes

TransitionGroup anime les listes v-for avec trois comportements : entrée (nouvel élément), sortie (élément retiré) et déplacement (élément existant changeant de position). La classe *-move anime la technique FLIP — Vue calcule les deltas de position et applique une transition de transform. Réglez position: absolute sur leave-active pour que l'élément partant sorte du flux, laissant les frères glisser en douceur en place.

vue3
<template>
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">{{ item.text }}</li>
  </TransitionGroup>
</template>

<style>
.list-enter-active, .list-leave-active { transition: all 0.5s; }
.list-enter-from, .list-leave-to { opacity: 0; transform: translateX(30px); }
/* the magic class for reordering */
.list-leave-active { position: absolute; }
.list-move { transition: transform 0.5s ease; }
</style>

État animé avec l'enveloppe <Transition>

On peut surcharger les noms de classes par défaut de Vue avec des classes custom — enter-active-class et leave-active-class. Cela permet de brancher sur des systèmes d'animation existants (Animate.css, utilitaires d'animation Tailwind, keyframes custom). Le pattern : définissez votre animation sur une classe, pointez la transition de Vue dessus. Cela fait le pont entre le cycle de vie de Vue et tout framework d'animation CSS.

vue3
<template>
  <button @click="show = !show">Toggle</button>
  <Transition
    enter-active-class="animate__animated animate__fadeIn"
    leave-active-class="animate__animated animate__fadeOut"
  >
    <div v-if="show" class="box">Content</div>
  </Transition>
</template>

<!-- combine with third-party animation libraries -->
<!-- Animate.css, Tailwind animations, custom keyframes -->

Suspense pour l'async

Suspense coordonne le setup async — quand un composant enfant utilise un top-level await, il suspend, et Suspense montre le #fallback à la place. Une fois tous les enfants async résolus, le slot par défaut se rend. Élégant pour les composants de fetch de données. Note : Suspense est encore expérimental dans Vue 3 — la gestion d'erreurs exige onErrorCaptured. En production, la plupart des équipes utilisent encore des composables + état de chargement.

vue3
<template>
  <Suspense>
    <template #default>
      <AsyncComponent />
    </template>
    <template #fallback>
      <div>Loading...</div>
    </template>
  </Suspense>
</template>

<!-- AsyncComponent uses top-level await -->
<script setup>
import { ref } from 'vue'
const data = ref(null)
// top-level await suspends the component
const res = await fetch('/api/data').then(r => r.json())
data.value = res
</script>
21

Teleport et Suspense

Bases de Teleport

Teleport rend le contenu vers un élément DOM ailleurs dans le document (souvent au niveau du body), mais le composant garde le contexte réactif de son parent, props, emits, etc. Cela résout les soucis de z-index/overflow des modales, tooltips et dropdowns qui seraient rognés par un overflow:hidden parent ou des contextes d'empilement. Le sélecteur 'to' cible l'élément de destination.

vue3
<!-- Modal.vue -->
<template>
  <!-- the rendered content is moved to #modals in the DOM,
       but keeps the component's reactive context -->
  <Teleport to="#modals">
    <div class="modal">
      <h2>{{ title }}</h2>
      <slot />
      <button @click="$emit('close')">Close</button>
    </div>
  </Teleport>
</template>

<!-- index.html must have -->
<!-- <div id="app"></div> -->
<!-- <div id="modals"></div> -->

Teleport conditionnel

La prop disabled permet de téléporter conditionnellement — quand true, le contenu se rend en place (sans téléport). Utile quand le même composant s'utilise dans des contextes différents (ex. un tooltip à téléporter dans une mise en page normale mais inline dans une autre modale). Plusieurs Teleports visant le même élément s'ajoutent dans l'ordre de rendu. Teleport marche avec v-if à l'intérieur.

vue3
<template>
  <!-- disabled: render in place (not teleported) -->
  <Teleport :to="target" :disabled="inline">
    <div class="popup" v-if="show">...</div>
  </Teleport>
</template>

<script setup>
const props = defineProps({
  inline: Boolean  // if true, render inline instead of teleporting
})
const target = '#popups'
</script>

<!-- Multiple Teleports to same target: appended in order -->

Teleport pour modales et notifications

Teleport vers body est le pattern standard des modales — la modale échappe à toute contrainte d'overflow/transform/z-index parente. Combinez à Transition pour l'animation d'entrée/sortie. Le @click.self sur le fond ferme au clic extérieur (mais pas sur le contenu). Les slots laissent le parent personnaliser entièrement l'en-tête, le corps et le footer de la modale pendant que le composant modale gère positionnement et animation.

vue3
<!-- components/Modal.vue -->
<template>
  <Teleport to="body">
    <Transition name="modal">
      <div v-if="show" class="modal-backdrop" @click.self="$emit('close')">
        <div class="modal-content">
          <header><slot name="header" /></header>
          <slot />
          <footer><slot name="footer" /></footer>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

Suspense avec setup async

Quand le setup d'un composant enfant utilise un top-level await, il retourne une Promise. Suspense l'attrape et montre le #fallback jusqu'à la résolution. Le résultat du setup du composant suspendu sert ensuite au rendu. Plusieurs enfants async se coordonnent — Suspense attend tous. onErrorCaptured attrape les erreurs de setup. Suspense est encore expérimental — pour la production, préférez un état de chargement manuel dans les composables.

vue3
<!-- Parent.vue -->
<template>
  <Suspense>
    <AsyncProfile :id="userId" />
    <template #fallback>
      <Spinner />
    </template>
  </Suspense>
</template>

<!-- AsyncProfile.vue -->
<script setup>
const props = defineProps(['id'])
// top-level await suspends this component
const profile = await fetch(`/api/users/${props.id}`).then(r => r.json())
// component only renders after this resolves
</script>

Suspense imbriqué et composants async

Suspense peut s'imbriquer — chaque niveau gère sa propre frontière async. Le Suspense externe montre PageSkeleton pendant que Dashboard (et tout ce dont il a besoin) se charge ; le interne montre ChartSkeleton spécifiquement pour le graphique. Ce chargement granulaire améliore l'UX : la coquille de page apparaît d'abord, puis les sections individuelles se remplissent. Rappelez-vous que Suspense est expérimental — testez à fond et gérez les erreurs via onErrorCaptured.

vue3
<template>
  <Suspense>
    <template #default>
      <Dashboard>
        <Suspense>
          <template #default>
            <AsyncChart :data="data" />
          </template>
          <template #fallback>
            <ChartSkeleton />
          </template>
        </Suspense>
      </Dashboard>
    </template>
    <template #fallback>
      <PageSkeleton />
    </template>
  </Suspense>
</template>
22

Provide / Inject

Provide et Inject de base

provide() rend une valeur disponible à tous les composants descendants ; inject() la récupère n'importe où en aval de l'arbre. Cela évite le forage de props pour les composants profondément imbriqués. Le second argument d'inject est une valeur par défaut (utilisée si rien n'est fourni). Les refs fournies sont réactives — les descendants peuvent les muter et le parent voit les changements. Utilisez des clés Symbol pour éviter les collisions dans les grandes apps.

vue3
<!-- Parent.vue -->
<script setup>
import { provide, ref } from 'vue'

const theme = ref('dark')
const user = ref({ name: 'Alice' })

// provide to all descendants
provide('theme', theme)
provide('user', user)
</script>

<!-- DeepChild.vue (any level of nesting) -->
<script setup>
import { inject } from 'vue'

const theme = inject('theme', 'light')  // default 'light'
const user = inject('user')

// these are reactive refs, just like in the parent
</script>

État fourni en lecture seule

Utilisez readonly() pour exposer l'état sans permettre la mutation directe — les descendants doivent appeler les méthodes d'action fournies pour le changer. Ce pattern (ref mutable privé + vue publique readonly + méthodes d'action) est une alternative légère à Pinia pour un état à portée d'arbre de composants. Il impose le flux de données unidirectionnel et prévient les bugs de mutations aléatoires profondes dans l'arbre.

vue3
<!-- store.js (shared composable) -->
import { ref, readonly } from 'vue'

const _count = ref(0)  // private mutable state

export function useCountStore() {
  return {
    count: readonly(_count),  // consumers can't mutate
    increment: () => _count.value++  // only via action
  }
}

<!-- Provider.vue -->
<script setup>
import { provide } from 'vue'
import { useCountStore } from './store'

const store = useCountStore()
provide('countStore', store)
</script>

Clés d'injection typées

Utilisez InjectionKey<Ref<Type>> pour créer une clé symbol typée. Cela donne une inférence TypeScript complète — inject connaît le type de retour. Les clés symbol évitent les collisions de chaînes quand plusieurs bibliothèques fournissent des valeurs. Pour les singletons à l'échelle de l'app, préférez Pinia à provide/inject — Pinia a des devtools, la persistance et une meilleure testabilité. Utilisez provide/inject pour le contexte à portée d'arbre de composants (thème, formulaire, locale).

vue3
<!-- keys.ts -->
import type { InjectionKey, Ref } from 'vue'
import { inject, provide } from 'vue'

export const ThemeKey: InjectionKey<Ref<string>> = Symbol('theme')

<!-- Provider.vue -->
<script setup>
import { ref } from 'vue'
import { ThemeKey } from './keys'

const theme = ref('dark')
provide(ThemeKey, theme)
</script>

<!-- Consumer.vue -->
<script setup>
import { inject } from 'vue'
import { ThemeKey } from './keys'

// TS knows theme is Ref<string> | undefined
const theme = inject(ThemeKey)
// with default
const theme2 = inject(ThemeKey, ref('light'))
</script>

Mettre à jour les valeurs fournies

Le pattern recommandé : fournissez un objet contenant l'état réactif ET les méthodes pour le muter. Cela garde l'API explicite et prévient les mutations aléatoires. Les enfants déstructurent l'état et les actions. C'est essentiellement un mini-store — pour tout ce qui dépasse quelques valeurs, considérez un composable retournant la même forme, ou Pinia. La valeur fournie est réactive car elle contient une ref.

vue3
<!-- Provider.vue -->
<script setup>
import { ref, provide } from 'vue'

const count = ref(0)

// expose value + mutator together
provide('counter', {
  count,                       // reactive ref
  increment: () => count.value++,
  reset: () => count.value = 0
})
</script>

<!-- DeepChild.vue -->
<script setup>
import { inject } from 'vue'

const { count, increment, reset } = inject('counter')
// count is reactive, increment/reset are actions
</script>

<template>
  <p>{{ count }}</p>
  <button @click="increment">+</button>
  <button @click="reset">Reset</button>
</template>

Provide au niveau app

app.provide() rend une valeur disponible à chaque composant de l'app — utile pour les constantes à l'échelle de l'app (URLs API, feature flags, config d'environnement). Contrairement au provide au niveau composant, ce n'est pas réactif par défaut (sauf si vous fournissez une ref). C'est une bonne façon d'injecter une config spécifique à l'environnement sans importer des fichiers env partout. Combinez à inject() dans tout composant pour accéder à ces globales.

vue3
<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

// app-level provide — available to ALL components
app.provide('apiUrl', 'https://api.example.com')
app.provide('apiKey', import.meta.env.VITE_API_KEY)

// useful for app-wide constants
app.provide('features', {
  darkMode: true,
  beta: false
})

app.mount('#app')

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.