Vue 3 tutorial – component events with defineEmits

Props come down from the parent to the child. To send something back up, a component emits an event and the parent listens for it, exactly as it would listen for a click.

The problem

Since the split in chapter 8, the cart lives in App.vue and the button in ProductDisplay.vue. The child cannot modify cart: it has no access to it, and a component has no business writing into another one’s state.

The right way to put it is not “the child adds to the cart”, but “the child announces that a click happened, and the parent decides what to do about it”.

Declaring and emitting

In the child, declare the events it emits, then emit:

<script setup>
const emit = defineEmits(['add-to-cart'])

function addToCart() {
  emit('add-to-cart')
}
</script>

<template>
  <button
    class="button"
    :class="{ disabledButton: !inStock }"
    :disabled="!inStock"
    @click="addToCart"
  >
    Ajouter au panier
  </button>
</template>

defineEmits is a compiler macro, like defineProps: no import needed. It returns the function used to emit.

Declaring the events is not compulsory, but it is worth doing: the list documents the component’s contract, your editor autocompletes from it, and Vue warns you if you emit a name that was never declared.

Listening on the parent side

A custom event is listened for with the same syntax as a native one:

<script setup>
import { ref } from 'vue'
import ProductDisplay from './components/ProductDisplay.vue'

const cart = ref(0)

function updateCart() {
  cart.value += 1
}
</script>

<template>
  <div class="cart">Panier ({{ cart }})</div>
  <ProductDisplay :premium="premium" @add-to-cart="updateCart" />
</template>

Click: the counter starts moving again. The button is in the child, the counter in the parent, and neither of them knows anything about the other’s state.

Passing data along

A realistic cart remembers what goes into it, not just how much. Pass the id of the variant as the second argument to emit:

<script setup>
function addToCart() {
  emit('add-to-cart', variants.value[selectedVariant.value].id)
}
</script>

The parent receives it as a parameter of its function:

<script setup>
const cart = ref([])

function updateCart(id) {
  cart.value.push(id)
}
</script>

<template>
  <div class="cart">Panier ({{ cart.length }})</div>
  <ProductDisplay :premium="premium" @add-to-cart="updateCart" />
</template>

cart has become an array, so the display uses cart.length. Add the blue T-shirt several times, then check in the Vue developer tools that the array really is filling up with 2234.

For several pieces of information, emit an object rather than a long list of arguments:

emit('add-to-cart', { id: variant.id, taille: 'M', quantite: 1 })

Naming events

Write the name in kebab-case: add-to-cart, not addToCart. HTML attributes are case-insensitive, a template written directly in a page would receive @addtocart and the listener would never fire. Inside a .vue file, Vue catches the case for you, but you may as well pick up the right habit.

Which way things flow

A review that arrives along this route can then be animated as it appears.

Remember these two sentences: props go down, events come up. The parent owns the data, the child asks for it to be changed. That is what makes the flow predictable, and the origin of any change always traceable.