Custom Events

    Unlike components and props, event names don’t provide any automatic case transformation. Instead, the name of an emitted event must exactly match the name used to listen to that event. For example, if emitting a camelCased event name:

    Listening to the kebab-cased version will have no effect:

    2. <my-component v-on:my-event="doSomething"></my-component>

    Since event names will never be used as variable or property names in JavaScript, there is no reason to use camelCase or PascalCase. Additionally, v-on event listeners inside DOM templates will be automatically transformed to lowercase (due to HTML’s case-insensitivity), so v-on:myEvent would become v-on:myevent — making myEvent impossible to listen to.

    For these reasons, we recommend you always use kebab-case for event names.

    1. app.component('custom-form', {
    2.   emits: ['in-focus', 'submit']
    3. })

    In the event a native event (e.g., click) is defined in the emits option, it will be overwritten by the event in the component instead of being treated as a native listener.

    TIP

    It is recommended to define all emitted events in order to better document how a component should work.

    Similar to prop type validation, an emitted event can be validated if it is defined with the Object syntax instead of the Array syntax.

    1. app.component('custom-form', {
    2.   emits: {
    3.     // No validation
    4.     click: null,
    6.     // Validate submit event
    7.     submit: ({ email, password }) => {
    8.       if (email && password) {
    9.         return true
    10.       } else {
    11.         console.warn('Invalid submit event payload!')
    12.         return false
    13.       }
    14.     }
    15.   },
    16.   methods: {
    17.       this.$emit('submit', { email, password })
    18.     }
    20. })

    By default, v-model on a component uses modelValue as the prop and update:modelValue as the event. We can modify these names passing an argument to v-model:

    In this case, child component will expect a foo prop and emits update:foo event to sync:

    1. const app = Vue.createApp({})
    3. app.component('my-component', {
    4.   props: {
    5.     foo: String
    6.   },
    7.   template: `
    8.     <input 
    9.       type="text"
    10.       v-bind:value="foo"
    11.       v-on:input="$emit('update:foo', $event.target.value)">
    12.   `
    13. })

    Note that this enables multiple v-model bindings on the same component, each syncing a different prop, without the need for extra options in the component:

    1. <my-component v-model:foo="bar" v-model:name="userName"></my-component>

    In 2.x, we have hard-coded support for modifiers like .trim on component v-model. However, it would be more useful if the component can support custom modifiers. In 3.x, modifiers added to a component v-model will be provided to the component via the modelModifiers prop:

    1. <my-component v-model.capitalize="bar"></my-component>
    1. <div id="app">
    2.   <my-component v-model.capitalize="myText"></my-component>
    3.   {{ myText }}
    4. </div>
    1. const app = Vue.createApp({
    3.     return {
    4.     }
    5.   }
    6. })
    8. app.component('my-component', {
    9.   props: {
    10.     modelValue: String,
    11.     modelModifiers: {
    12.       default: () => ({})
    13.     }
    14.   },
    15.   methods: {
    16.     emitValue(e) {
    17.       let value = e.target.value
    18.       if (this.modelModifiers.capitalize) {
    19.         value = value.charAt(0).toUpperCase() + value.slice(1)
    20.       }
    21.       this.$emit('update:modelValue', value)
    22.     }
    23.   },
    24.   template: `<input
    25.     type="text"
    26.     v-bind:value="modelValue"
    27.     v-on:input="emitValue">`
    28. })

    For v-model with arguments, the generated prop name will be arg + "Modifiers":