Overview
Attaches event listeners with automatic cleanup on scope disposal. Supports Window, Document, and HTMLElement targets with reactive events, listeners, and options.
Features
- Supports Window, Document, and HTMLElement targets
- Reactive targets, events, and listeners
- Event options support (capture, passive, once)
- Automatic removeEventListener on unmount
- Multiple overloads for type safety
- Convenience functions for common use cases
Function Signature
// HTMLElement target
function useEventListener<E extends keyof HTMLElementEventMap>(
target: MaybeRefOrGetter<HTMLElement | null | undefined>,
event: MaybeRefOrGetter<MaybeArray<E>>,
listener: MaybeRef<MaybeArray<(this: HTMLElement, event: HTMLElementEventMap[E]) => void>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
): CleanupFunction
// Document target
function useEventListener<E extends keyof DocumentEventMap>(
target: Document,
event: MaybeRefOrGetter<MaybeArray<E>>,
listener: MaybeRef<MaybeArray<(this: Document, event: DocumentEventMap[E]) => void>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
): CleanupFunction
// Window target
function useEventListener<E extends keyof WindowEventMap>(
target: Window,
event: MaybeRefOrGetter<MaybeArray<E>>,
listener: MaybeRef<MaybeArray<(this: Window, event: WindowEventMap[E]) => void>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
): CleanupFunction
Parameters
target
MaybeRefOrGetter<EventTarget | null | undefined>
The target to attach the event listener to (Window, Document, or HTMLElement).
event
MaybeRefOrGetter<MaybeArray<string>>
The event(s) to listen for. Can be a string or array of strings.
listener
MaybeRef<MaybeArray<EventHandler>>
The event listener(s). Can be a single function or array of functions.
options
MaybeRefOrGetter<boolean | AddEventListenerOptions>
Event listener options (capture, passive, once).
Return Value
Function to remove the event listener.
Examples
Basic usage
import { ref } from 'vue'
import { useEventListener } from '@vuetify/v0'
const buttonRef = ref<HTMLElement>()
useEventListener(buttonRef, 'click', (event) => {
console.log('Button clicked', event)
})
Multiple events
const inputRef = ref<HTMLInputElement>()
useEventListener(inputRef, ['input', 'blur', 'focus'], (event) => {
console.log('Input event:', event.type)
})
Reactive events
const isTouchDevice = ref(false)
const eventType = computed(() =>
isTouchDevice.value ? 'touchstart' : 'mousedown'
)
useEventListener(element, eventType, handleInteraction)
Multiple listeners
const trackClick = () => console.log('Analytics')
const updateUI = () => console.log('UI update')
useEventListener(button, 'click', [trackClick, updateUI])
Event options
// Passive listener for better scroll performance
useEventListener(
scrollContainer,
'scroll',
handleScroll,
{ passive: true }
)
// Capture phase
useEventListener(
document,
'click',
handleCapture,
{ capture: true }
)
Manual cleanup
const stopListening = useEventListener(element, 'click', handler)
// Remove listener early
stopListening()
Window events
import { useWindowEventListener } from '@vuetify/v0'
const windowSize = ref({ width: 0, height: 0 })
useWindowEventListener('resize', () => {
windowSize.value = {
width: window.innerWidth,
height: window.innerHeight
}
})
Document events
import { useDocumentEventListener } from '@vuetify/v0'
useDocumentEventListener('keydown', (e) => {
if (e.ctrlKey && e.key === 's') {
e.preventDefault()
saveDocument()
}
})
Convenience Functions
useWindowEventListener
function useWindowEventListener<E extends keyof WindowEventMap>(
event: MaybeRefOrGetter<MaybeArray<E>>,
listener: MaybeRef<MaybeArray<(this: Window, event: WindowEventMap[E]) => void>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
): CleanupFunction
useDocumentEventListener
function useDocumentEventListener<E extends keyof DocumentEventMap>(
event: MaybeRefOrGetter<MaybeArray<E>>,
listener: MaybeRef<MaybeArray<(this: Document, event: DocumentEventMap[E]) => void>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>
): CleanupFunction
Notes
- Listeners are automatically removed on scope disposal
- Reactive changes to event, listener, or options are automatically handled
- SSR-safe: window/document helpers return no-op functions during SSR
- Use the
once option for one-time event listeners
