La Vue Composition API est le style d'écriture moderne introduit avec Vue 3 : elle permet de regrouper la logique d'un composant dans une seule fonction setup au lieu de la disperser entre des options comme data, methods et computed. Dans ce guide, je présente les outils essentiels — ref, reactive, computed et watch — avec de vrais exemples, pour garder des composants nets et réutilisables même quand ils grandissent.
De l'Options API à la Composition API
Dans l'Options API classique, l'état d'un composant, ses valeurs calculées et ses méthodes vivent dans des blocs séparés. Cela convient aux petits composants, mais à mesure qu'une fonctionnalité grossit, le code lié à une même préoccupation se retrouve éparpillé dans le fichier. La Composition API permet de garder la logique liée au même endroit : l'état d'un compteur, sa valeur dérivée et sa fonction se côtoient.
Les deux styles sont entièrement pris en charge dans Vue 3 — la Composition API est une option, pas une obligation. Son plus grand avantage apparaît lorsqu'on écrit de la logique partageable (les composables).
setup et <script setup>
La façon la plus pratique d'utiliser la Composition API est la syntaxe de compilation <script setup>. Chaque variable et fonction que vous y déclarez est automatiquement exposée au template, et aucune instruction return n'est nécessaire.
<script setup>
import { ref } from 'vue'
const count = ref(0)
function increment() {
count.value++
}
</script>
<template>
<button @click="increment">Compteur : {{ count }}</button>
</template>Remarque : en JavaScript, on lit la valeur via count.value, mais dans le template Vue déballe .value automatiquement ; on écrit simplement count.
Valeurs réactives avec ref
Utilisez ref pour les valeurs simples (nombre, chaîne, booléen). Elle renvoie un objet dont la valeur réelle se trouve dans sa propriété .value. C'est la base de la réactivité qui permet à Vue de mettre à jour le DOM quand la valeur change.
- Lecture/écriture :
const name = ref('Ada')→name.value = 'Grace' - Idéal pour les primitifs : string, number, boolean.
- Peut aussi contenir un objet : placez un objet dans un
refet Vue rend son contenu profondément réactif viareactive.
État d'objet avec reactive
Quand vous voulez gérer plusieurs champs liés ensemble, reactive convient bien. Il prend un objet et le transforme en proxy profondément réactif ; ici, on n'écrit pas .value, on accède directement aux propriétés.
import { reactive } from 'vue'
const form = reactive({
email: '',
agreed: false,
})
function submit() {
console.log(form.email, form.agreed)
}Lequel choisir ? Une règle pratique : ref pour les primitifs et les morceaux d'état isolés, reactive pour un formulaire ou un objet qui forme logiquement un tout. Rappelez-vous qu'on ne peut pas réassigner un objet reactive en entier (cela casserait la référence) — mettez plutôt ses champs à jour, ou préférez ref.
Valeurs dérivées avec computed
computed produit des valeurs calculées à partir d'autres sources réactives, mises en cache jusqu'à ce que leurs dépendances changent. Au lieu de recalculer le même résultat sans cesse dans le template, vous le définissez une fois.
import { ref, computed } from 'vue'
const price = ref(100)
const quantity = ref(3)
const total = computed(() => price.value * quantity.value)total se comporte comme un ref : total.value en JavaScript, {{ total }} dans le template. Quand price ou quantity change, Vue recalcule total automatiquement.
Effets de bord avec watch et watchEffect
Pour les effets de bord — déclencher une requête réseau, écrire dans localStorage — quand une valeur change, on utilise watch. Il surveille une source précise et vous donne l'ancienne et la nouvelle valeur.
import { ref, watch } from 'vue'
const query = ref('')
watch(query, (nouveau, ancien) => {
console.log(`'${ancien}' -> '${nouveau}'`)
})watchEffect, lui, suit automatiquement les valeurs réactives utilisées en son sein et s'exécute aussitôt une fois ; il est plus concis pour les cas simples. Choisissez watch quand vous voulez voir exactement quelle dépendance vous suivez, et watchEffect quand vous voulez dire « suis tout ce que j'utilise ».
Composables : réutiliser la logique
La vraie force de la Composition API est d'extraire la logique dans une fonction et de la partager entre composants. Par convention, ces fonctions portent un préfixe use.
// useCounter.js
import { ref } from 'vue'
export function useCounter(start = 0) {
const count = ref(start)
const increment = () => count.value++
const reset = () => (count.value = start)
return { count, increment, reset }
}Désormais, n'importe quel composant peut réutiliser la même logique avec const { count, increment } = useCounter(10). Contrairement aux mixins, on sait clairement d'où vient chaque valeur et on évite les conflits de noms.
Questions fréquentes
Dois-je utiliser ref ou reactive ?
Utilisez ref pour les primitifs et l'état isolé, et reactive pour les objets/formulaires qui forment un tout logique. Beaucoup d'équipes emploient ref partout par souci de cohérence ; les deux sont corrects.
L'Options API est-elle désormais considérée comme obsolète ?
Non. L'Options API reste entièrement prise en charge et n'est pas supprimée. La Composition API est une option supplémentaire qui brille dans les gros composants et la logique partagée.
Pourquoi n'écrit-on pas .value dans le template ?
Quand Vue compile le template, il déballe automatiquement les ref de premier niveau. C'est pourquoi on écrit count dans le template mais count.value en JavaScript.
Vous envisagez de migrer votre projet Vue vers la Composition API ? De l'architecture des composants à la conception des composables, nous pouvons bâtir une structure propre ensemble — contactez-moi.