useEventListener

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

Copy Markdown

Intermediate100% coverageMar 3, 2026

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.

vue

<script setup lang="ts">
  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>

Architecture

useEventListener is the foundational event composable that others build upon:

Reactivity

Property/Method	Reactive	Notes
`target`		Accepts MaybeRefOrGetter, watched for changes
`event`		Accepts MaybeRefOrGetter, watched for changes
`listener`		Accepts MaybeRef, watched for changes
`options`		Accepts MaybeRefOrGetter, watched for changes

Tip

Reactive inputs All parameters accept reactive values. When any input changes, listeners are automatically re-registered.

API Reference

The following API details are for the useEventListener composable.

Functions

useEventListener

(target: MaybeRefOrGetter<EventTarget | null | undefined>, event: MaybeRefOrGetter<MaybeArray<string>>, listener: MaybeRef<MaybeArray<EventHandler<Event>>>, options?: MaybeRefOrGetter<boolean | AddEventListenerOptions> | undefined) => CleanupFunction

Attaches an event listener to a target.

useWindowEventListener

(event: MaybeRefOrGetter<MaybeArray<E>>, listener: MaybeRef<MaybeArray<(this: Window, event: WindowEventMap[E]) => void>>, options?: MaybeRefOrGetter<boolean | AddEventListenerOptions> | undefined) => CleanupFunction

Attaches an event listener to the window.

useDocumentEventListener

(event: MaybeRefOrGetter<MaybeArray<E>>, listener: MaybeRef<MaybeArray<(this: Document, event: DocumentEventMap[E]) => void>>, options?: MaybeRefOrGetter<boolean | AddEventListenerOptions> | undefined) => CleanupFunction

Attaches an event listener to the document.