/vue-options-api-best-practices

Explicitly Type Event Handlers in Options API Methods

Impact: MEDIUM - Without explicit type annotations, event handler parameters in Options API methods are typed as any. This defeats TypeScript's purpose, causing noImplicitAny errors in strict mode and losing type safety for DOM event properties.

Task Checklist

• Always add type annotations to event handler method parameters
• Use the correct DOM event type (Event, MouseEvent, KeyboardEvent, etc.)
• Use type assertions for event.target when accessing element-specific properties
• Enable strict: true in tsconfig.json to catch implicit any errors

The Problem

import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    // BAD - 'event' is implicitly 'any'
    handleClick(event) {
      console.log(event.target.value)  // No type checking!
    },

    // BAD - Causes error with noImplicitAny
    handleInput(event) {
      // Error: Parameter 'event' implicitly has an 'any' type
      this.searchTerm = event.target.value
    }
  }
})

The Solution: Explicit Event Types

import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      searchTerm: ''
    }
  },
  methods: {
    // GOOD - Explicit Event type
    handleClick(event: MouseEvent) {
      console.log(event.clientX, event.clientY)
      // Cast target for element-specific properties
      const button = event.target as HTMLButtonElement
      console.log(button.disabled)
    },

    // GOOD - Explicit Event type with target assertion
    handleInput(event: Event) {
      const input = event.target as HTMLInputElement
      this.searchTerm = input.value
    },

    // GOOD - KeyboardEvent for keyboard handlers
    handleKeydown(event: KeyboardEvent) {
      if (event.key === 'Enter') {
        this.submit()
      }
    }
  }
})

Common DOM Event Types

Type Assertions for event.target

event.target is typed as EventTarget | null, which is too generic. Use type assertions:

methods: {
  // Input element
  onInputChange(event: Event) {
    const target = event.target as HTMLInputElement
    console.log(target.value)
    console.log(target.checked)  // for checkboxes
  },

  // Select element
  onSelectChange(event: Event) {
    const target = event.target as HTMLSelectElement
    console.log(target.value)
    console.log(target.selectedIndex)
  },

  // Form element
  onFormSubmit(event: SubmitEvent) {
    event.preventDefault()
    const form = event.target as HTMLFormElement
    const formData = new FormData(form)
  },

  // Using currentTarget (often more reliable)
  onButtonClick(event: MouseEvent) {
    // currentTarget is the element the handler is attached to
    const button = event.currentTarget as HTMLButtonElement
    console.log(button.dataset.id)
  }
}

Template Usage

<template>
  <div>
    <!-- Mouse events -->
    <button @click="handleClick">Click me</button>

    <!-- Input events -->
    <input @input="handleInput" @keydown="handleKeydown" />

    <!-- Form events -->
    <form @submit.prevent="handleSubmit">
      <button type="submit">Submit</button>
    </form>
  </div>
</template>

With Custom Component Events

For custom component events, type based on what the component emits:

methods: {
  // Child emits: emit('update', { id: number, value: string })
  handleChildUpdate(payload: { id: number; value: string }) {
    console.log(payload.id, payload.value)
  },

  // Child emits primitive: emit('change', newValue)
  handleValueChange(newValue: number) {
    this.count = newValue
  }
}

Generic Event Handler Pattern

For reusable handlers:

methods: {
  // Generic handler that works with any input
  updateField<T extends HTMLInputElement | HTMLTextAreaElement>(
    field: keyof typeof this.$data,
    event: Event
  ) {
    const target = event.target as T
    ;(this as any)[field] = target.value
  }
}

Why currentTarget vs target?

• target: The element that triggered the event (could be a child)
• currentTarget: The element the event listener is attached to

methods: {
  // If button contains <span>Click</span>, clicking the span:
  // - event.target = span
  // - event.currentTarget = button
  handleClick(event: MouseEvent) {
    // Use currentTarget when you want the handler's element
    const button = event.currentTarget as HTMLButtonElement
  }
}

Reference

• Vue.js TypeScript with Options API - Typing Event Handlers
• MDN Event Interface
• TypeScript DOM Types