charging-cabinet/software/h5-uniapp/.agents/skills/vue-best-practices/reference/declare-emits-for-documentation.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Always Declare Emits for Documentation and Validation	MEDIUM	Undeclared emits cause warnings, break TypeScript inference, and prevent event validation	best-practice	vue3 emits defineEmits component-events typescript documentation

Always Declare Emits for Documentation and Validation

Impact: MEDIUM - Declaring emitted events with defineEmits() or the emits option is technically optional, but strongly recommended. Without declarations, Vue shows runtime warnings, TypeScript can't infer event types, and you lose the ability to validate event payloads.

Declared emits also serve as self-documentation, making it immediately clear what events a component can emit.

Task Checklist

• Use defineEmits() in <script setup> to declare all events
• Use emits option when not using <script setup>
• Add TypeScript types for event payloads
• Consider adding validation functions for complex payloads
• Document the purpose of each event

The Warning

When you emit without declaring:

<script setup>
// No defineEmits declaration
function handleClick() {
  emit('select', item) // Vue warns in dev mode
}
</script>

Vue warns:

[Vue warn]: Component emitted event "select" but it is neither declared
in the emits option nor as an "onSelect" prop.

Basic Declaration

Correct - Array syntax:

<script setup>
const emit = defineEmits(['submit', 'cancel', 'update'])

function handleSubmit() {
  emit('submit', formData)
}

function handleCancel() {
  emit('cancel')
}
</script>

Correct - Options API:

export default {
  emits: ['submit', 'cancel', 'update'],

  methods: {
    handleSubmit() {
      this.$emit('submit', this.formData)
    }
  }
}

TypeScript Typed Emits

Correct - Type-based declaration (recommended for TypeScript):

<script setup lang="ts">
interface User {
  id: number
  name: string
}

const emit = defineEmits<{
  submit: [data: FormData]
  cancel: []
  'update:modelValue': [value: string]
  select: [user: User, index: number]
}>()

// Now TypeScript enforces correct payloads
emit('submit', formData) // OK
emit('submit') // Error: Expected 1 argument
emit('select', user) // Error: Expected 2 arguments
emit('unknown') // Error: Unknown event
</script>

Alternative syntax (Vue 3.3+):

<script setup lang="ts">
const emit = defineEmits<{
  (e: 'submit', data: FormData): void
  (e: 'cancel'): void
  (e: 'update:modelValue', value: string): void
}>()
</script>

Event Validation

You can validate event payloads at runtime:

Correct - Validation functions:

<script setup>
const emit = defineEmits({
  // No validation, just declaration
  cancel: null,

  // Validate payload
  submit: (payload) => {
    if (!payload.email) {
      console.warn('Submit event requires email')
      return false
    }
    return true
  },

  // Validate with type checking
  click: (id) => typeof id === 'number'
})
</script>

Returning false from a validator logs a console warning but doesn't prevent the event from being emitted.

Benefits of Declaring Emits

1. Fallthrough Attribute Separation

Without declaration, native event listeners fall through to the root element:

<!-- ParentComponent.vue -->
<ChildComponent @click="handleClick" />

<!-- ChildComponent.vue - WITHOUT emits declaration -->
<template>
  <!-- Native click listener falls through to button -->
  <button>Click me</button>
</template>

With declaration, Vue knows it's a component event:

<script setup>
// Now Vue knows 'click' is a component event, not native
const emit = defineEmits(['click'])
</script>

2. Self-Documentation

<script setup>
// Clear contract: this component emits these events
const emit = defineEmits<{
  'row-click': [row: TableRow]
  'row-select': [row: TableRow, selected: boolean]
  'page-change': [page: number]
  'sort-change': [column: string, direction: 'asc' | 'desc']
}>()
</script>

3. IDE Support

With declarations, your IDE can:

• Autocomplete event names when using the component
• Show event payload types
• Warn about typos in event names
• Navigate to event definitions

$emit in Template vs emit in Script

<script setup>
// $emit is available in template, but...
// emit() is needed in <script setup>
const emit = defineEmits(['submit'])

function handleSubmit() {
  // $emit doesn't work here - use emit()
  emit('submit', data)
}
</script>

<template>
  <!-- $emit works in template -->
  <button @click="$emit('submit', data)">Submit</button>

  <!-- Or use the declared emit function -->
  <button @click="emit('submit', data)">Submit</button>
</template>

Reference

• Vue.js Component Events - Declaring Emitted Events
• Vue.js Component Events - Events Validation
• Vue 3 Migration - emits Option