How to use VueJs 3 – Custom event declaration

Finally after a long wait VueJs 3 has been release, and with it, lots of exciting change have also landed on our doorstep.

In this article, we are going to cover a breaking change (or more precisely, a compiler error), that will be triggered when using custom events.

If you have ever used VueJs for more than just create an Hello world application, you have surely used Custom Events before, and you are surely in need to continue to read on.

If you do not want to read on, and just get the code that will be used in this article, you can access the following stackblitz code

Custom Event example

Just to remind all the readers about custom event, we are going to cover a very simple cases. In VueJs (as with many different frameworks), events are used for children component to “bubble” data up to its parents.

In the following example we are going to define a child component that would emit a value to its parents when clicked.

//Child component
<template>
  <div>
    <button @click="$emit('SimpleEvent', 'string')">Click me</button>
  </div>
</template>

//Parent component
<template>
  <div id="app">
    <SimpleEvent @simple-event="event => alert(event)" />
  </div>
</template>

Events can be emitted by calling $emit method. The first argument is the name of the event that we want to emit, and the second is the actual value to be emitted (this can be a simple string, or any other value in JS).

The parent can then listen to an event by using the @event-name method. This method will trigger a callback, with the value being passed by the event itself.

VueJs 3 Custom event declaration

In the second version VueJs, the above code was all that was needed for the emits to be used. But with the latest release of the framework (vueJs 3), we are in need to make some small modification to our code for it to work.

Unfortunately, if we would run the above code in a Vue 3 application we will receive the following error:

The above warning is issued because VueJs 3 requires events to be declared. This will ensure the proper use of them.

If you have used VueJs, then you have surely used Props declaration (more information can be found in this article). The reason why I mention props, is because the code required is very similar.

Simple Custom event declaration

As with the above mentioned article, we are going to introduce this new declaration in small steps. In this section we are going to define a very simple declaration that is required for the warning to go.

<template>
  <div>
    <h2>Simple event</h2>
    <button @click="$emit('SimpleEvent', 'string')">Simple event</button>
  </div>
</template>

<script>
export default {
  name: "SimpleEvent",
  emits: ["SimpleEvent"]
};
</script>

The above code should not look so different after all, the main change is the introduction of a new component property called “emits”. In the above code we have used a very simple “array” that will include a list of string that is equivalent to the messages emitted by our component (in our case called SimpleEvent).

Custom event with validation

Differently from the property declaration that has many different possible options, the Custom events just has a simple options “validator”.

The validator will include a callback that will be triggered every time the event is emitted. As with all validator the function will be successful if it returns true and trigger a warning if it fails.

The code will look like this:

<template>
  <div>
    <h2>Validated custom event</h2>
    <button @click="$emit('ValidatedEvent', 'None')">
      Validated event wrong value
    </button>
    <button @click="$emit('ValidatedEvent', 'Critical')">
      Validated event correct value
    </button>
  </div>
</template>

<script>
export default {
  name: "ValidatedEvent",
  emits: {
    ValidatedEvent: value => ["Critical", "Medium", "Minor"].includes(value)
  }
};
</script>

The above code has a few changes. Firstly we have changed the emits to be an object (instead than an array). Secondly, as above mentioned, we have added a simple callback that will return true if the value emitted is part of the provided array (Critical, Medium, Minor). Lastly, the component also has two buttons to showcase a correct and incorrect implementation of the message.

Conclusion

The above is just one of many changes introduced by the fantastic vueJs core team in their latest release of the framework. I really hope this article has been helpful in cleaning some doubt in the new custom event declaration.