useEventListener ​
Use EventListener with ease. Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
Usage ​
js
import { useEventListener } from '@vueuse/core'
useEventListener(document, 'visibilitychange', (evt) => {
console.log(evt)
})
You can also pass a ref as the event target, useEventListener
will unregister the previous event and register the new one when you change the target.
ts
import { useEventListener } from '@vueuse/core'
const element = ref<HTMLDivElement>()
useEventListener(element, 'keydown', (e) => {
console.log(e.key)
})
js
import { useEventListener } from '@vueuse/core'
const element = ref()
useEventListener(element, 'keydown', (e) => {
console.log(e.key)
})
vue
<template>
<div v-if="cond" ref="element">
Div1
</div>
<div v-else ref="element">
Div2
</div>
</template>
You can also call the returned to unregister the listener.
ts
import { useEventListener } from '@vueuse/core'
const cleanup = useEventListener(document, 'keydown', (e) => {
console.log(e.key)
})
cleanup() // This will unregister the listener.
Note if your components also run in SSR (Server Side Rendering), you might get errors (like document is not defined
) because DOM APIs like document
and window
are not available in Node.js. To avoid that you can put the logic inside onMounted
hook.
ts
// onMounted will only be called in the client side, so it guarantees the DOM APIs are available.
onMounted(() => {
useEventListener(document, 'keydown', (e) => {
console.log(e.key)
})
})
Type Declarations ​
Show Type Declarations
typescript
interface InferEventTarget<Events> {
addEventListener: (event: Events, fn?: any, options?: any) => any
removeEventListener: (event: Events, fn?: any, options?: any) => any
}
export type WindowEventName = keyof WindowEventMap
export type DocumentEventName = keyof DocumentEventMap
export interface GeneralEventListener<E = Event> {
(evt: E): void
}
/**
* Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
*
* Overload 1: Omitted Window target
*
* @see https://vueuse.org/useEventListener
* @param event
* @param listener
* @param options
*/
export declare function useEventListener<E extends keyof WindowEventMap>(
event: Arrayable<E>,
listener: Arrayable<(this: Window, ev: WindowEventMap[E]) => any>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
* Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
*
* Overload 2: Explicitly Window target
*
* @see https://vueuse.org/useEventListener
* @param target
* @param event
* @param listener
* @param options
*/
export declare function useEventListener<E extends keyof WindowEventMap>(
target: Window,
event: Arrayable<E>,
listener: Arrayable<(this: Window, ev: WindowEventMap[E]) => any>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
* Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
*
* Overload 3: Explicitly Document target
*
* @see https://vueuse.org/useEventListener
* @param target
* @param event
* @param listener
* @param options
*/
export declare function useEventListener<E extends keyof DocumentEventMap>(
target: DocumentOrShadowRoot,
event: Arrayable<E>,
listener: Arrayable<(this: Document, ev: DocumentEventMap[E]) => any>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
* Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
*
* Overload 4: Explicitly HTMLElement target
*
* @see https://vueuse.org/useEventListener
* @param target
* @param event
* @param listener
* @param options
*/
export declare function useEventListener<E extends keyof HTMLElementEventMap>(
target: MaybeRefOrGetter<HTMLElement | null | undefined>,
event: Arrayable<E>,
listener: (this: HTMLElement, ev: HTMLElementEventMap[E]) => any,
options?: boolean | AddEventListenerOptions,
): () => void
/**
* Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
*
* Overload 5: Custom event target with event type infer
*
* @see https://vueuse.org/useEventListener
* @param target
* @param event
* @param listener
* @param options
*/
export declare function useEventListener<
Names extends string,
EventType = Event,
>(
target: InferEventTarget<Names>,
event: Arrayable<Names>,
listener: Arrayable<GeneralEventListener<EventType>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
/**
* Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
*
* Overload 6: Custom event target fallback
*
* @see https://vueuse.org/useEventListener
* @param target
* @param event
* @param listener
* @param options
*/
export declare function useEventListener<EventType = Event>(
target: MaybeRefOrGetter<EventTarget | null | undefined>,
event: Arrayable<string>,
listener: Arrayable<GeneralEventListener<EventType>>,
options?: MaybeRefOrGetter<boolean | AddEventListenerOptions>,
): Fn
Source ​
Contributors ​
Anthony Fu
丶远方
Julien Le Coupanec
Michael J. Roberts
James Garbutt
vaakian X
sun0day
Alejandro Arevalo
Jelf
Alex Kozack
lstoeferle
Antério Vieira
Changelog ​
v10.8.0
on 2/20/2024a086e
- fix: stricter typesv10.4.1
on 8/28/2023v10.3.0
on 7/30/2023v10.0.0-beta.5
on 4/13/2023cb644
- refactor!: remove isFunction
and isString
utilsv10.0.0-beta.4
on 4/13/20234d757
- feat(types)!: rename MaybeComputedRef
to MaybeRefOrGetter
0a72b
- feat(toValue): rename resolveUnref
to toValue
v9.13.0
on 2/18/2023103d6
- feat: support reactive optionsv9.10.0
on 1/3/2023v9.5.0
on 11/9/2022