useEventListener

A composable for handling DOM events with automatic cleanup on component unmount.

Usage

The useEventListener composable attaches event listeners to DOM elements (Window, Document, or HTMLElement) with automatic cleanup when the component is unmounted. It supports reactive targets, multiple events, and multiple handlers.

<script setup>
import { useEventListener, useWindowEventListener, useDocumentEventListener } from '@vuetify/v0'
import { ref, useTemplateRef } from 'vue'

// Track window dimensions
const windowSize = ref({ width: window.innerWidth, height: window.innerHeight })
useWindowEventListener('resize', () => {
  windowSize.value = {
    width: window.innerWidth,
    height: window.innerHeight
  }
})

// Handle keyboard shortcuts
useDocumentEventListener('keydown', (e) => {
  if (e.ctrlKey && e.key === 's') {
    e.preventDefault()
    console.log('Save shortcut triggered')
  }
})

// Element-specific listener
const button = useTemplateRef('button')
useEventListener(button, 'click', () => {
  console.log('Button clicked!')
})
</script>

<template>
  <div>
    <p>Window: {{ windowSize.width }}x{{ windowSize.height }}</p>
    <button ref="button">Click me</button>
  </div>
</template>

API

useEventListener

• Type

  function useEventListener(
    target: Window | Document | MaybeRefOrGetter<HTMLElement | EventTarget | null | undefined>,
    event: MaybeRefOrGetter<MaybeArray<string>>,
    listener: MaybeRef<MaybeArray<EventHandler>>,
    options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
  ): CleanupFunction

• Details

  Attaches event listeners to DOM elements with automatic cleanup. The target, event type, and listener can all be reactive values.

• Parameters

  • target: The target element to attach the listener to (Window, Document, or HTMLElement ref)
  • event: Event name(s) to listen for (can be string or array of strings)
  • listener: Event handler function(s) (can be single function or array)
  • options: Optional event listener options (capture, passive, once, etc.)

• Returns

  • stop: Function to manually remove the event listener

• Example

  const element = useTemplateRef('element')
  const stop = useEventListener(element, 'click', (e) => {
    console.log('Clicked!', e)
  })
  
  // Manual cleanup if needed
  stop()

useWindowEventListener

• Type

  function useWindowEventListener(
    event: MaybeRefOrGetter<MaybeArray<keyof WindowEventMap>>,
    listener: MaybeRef<MaybeArray<WindowEventHandler>>,
    options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
  ): CleanupFunction

• Details

  Convenience function for attaching event listeners to the window object.

• Example

  useWindowEventListener('resize', () => {
    console.log('Window resized')
  })

useDocumentEventListener

• Type

  function useDocumentEventListener(
    event: MaybeRefOrGetter<MaybeArray<keyof DocumentEventMap>>,
    listener: MaybeRef<MaybeArray<DocumentEventHandler>>,
    options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
  ): CleanupFunction

• Details

  Convenience function for attaching event listeners to the document object.

• Example

  useDocumentEventListener('keydown', (e) => {
    if (e.key === 'Escape') {
      closeModal()
    }
  })