Why does this work? (event-listner prop)

[Serhansolo]

Hi I am confused over here,

I made a modal component that I can feed with function props. These can even be validated using runtime validation (as stated here). It feels like an anti-pattern as soon as you use a prop name called "onXxx" in this example, I used onCallback. In this example I made the prop a promise so I can showcase the ability to run async calls like this. You can even use the prop to add a conditional in the template-tag or in the script-tag

CallbackComponent.vue

<template>
  <div>
    <button @click.self="runCallstack">Callback button</button>
    <p v-if="props.onCallback">Callback function detected</p>
    <p>
      {{ callbackCalled }}
    </p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "process";
import { withDefaults } from "vue";

interface ComponentProps {
  onCallback?: () => Promise<void>;
}

const props = withDefaults(defineProps<ComponentProps>(), {
  onCallback: undefined,
});

const callbackCalled = ref(false);

const emit = defineEmits(["callbackCalled", "callbackFailed"]);

async function runCallstack() {
  try {
    // Do some pre work
    if (props.onCallback) await props.onCallback();
    // Do some post work
  } catch {
    // maybe do a catch or something and emit that
    emit("callbackFailed");
  } finally {
    // when done with it all emit that
    emit("callbackCalled");
  }
}
</script>

The fun actually starts when you use this component.

App.vue

<callback-component @callback="async () => console.log('hello world')" />

As you can see, I can use the event listener syntax on the prop! And this won't give me any errors… in fact, it works like a charm. Why? I can also add @callback-called and @callback-failed listeners to react to the other emits.

Can anyone send me a piece of the docs or explain this? I haven't found any references to this behavior.

[skirtles-code]

The template attributes all get mapped down into VNode props (not to be confused with component props). The VNode props are the properties passed into the h() calls in a render function.

For v-on (or equivalently @), it'll be mapped onto a VNode prop prefixed with on. e.g. @click becomes the VNode prop onClick. That part is documented at:

• https://vuejs.org/guide/extras/render-function.html#v-on

There are a few other places in the docs that allude to this, but that's probably the most explicit. You can also see this using the Vue Playground to inspect the compiled output for a template with a listener.

Inside the child component, any VNode prop can be turned into a component prop by listing it in props (or equivalent with defineProps). While it is more common for events to use emits (or equivalently defineEmits), it is also possible to use props for events. One use case for this is detecting whether an event listener is passed, which isn't possible when using emits.

Another case where this is relevant is fallthrough attributes. VNode props that aren't listed in either props or emits end up in the $attrs. This includes event listeners passed in using v-on, which are copied from the VNode props to the $attrs with the on prefix. The $attrs needs to be compatible with v-bind="$attrs", but that's fine because using v-bind with an onClick property works out the same as using @click. There is some acknowledgement of this at https://vuejs.org/guide/components/attrs.html#disabling-attribute-inheritance, which notes that 'A v-on event listener like @click will be exposed on the object as a function under $attrs.onClick'.

While it isn't documentation, also note the warning message in this example:

• Playground

This warning acknowledges that an emitted event can either be declared in the usual way (using emits) or as an on prop.

[Serhansolo]

Well thats exactly what we concluded at work after some more research. Sooo it’s an advanced feature then?

we found that using an event as a prop obscures expectations from the developer side. Because mainstream thought is that events === emits.

Although through careful separation of concerns the developer won’t need to know whats happening under the hood. Imho the added bonus to do a pre-flight check on the incoming listener for existence to then make your component smarter by reacting to that is awesome! I think I will use it sparingly.

Why is this not documented more clearly, shouldn’t it be? Since it is a feature by design, there should be some mentions of it in the main docs.