Skip to content

useEventListener

Category
Export Size
588 B
Last Changed
last week

Use EventListener with ease. Register using addEventListener on mounted, and removeEventListener automatically on unmounted.

Usage

ts
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.

vue
<script setup lang="ts">
import { 
useEventListener
} from '@vueuse/core'
import {
useTemplateRef
} from 'vue'
const
element
=
useTemplateRef
('element')
useEventListener
(
element
, 'keydown', (
e
) => {
console
.
log
(
e
.
key
)
}) </script> <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
ts
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 type
ShadowRootEventName
= keyof ShadowRootEventMap
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 */ export declare function
useEventListener
<
E
extends keyof WindowEventMap>(
event
:
MaybeRefOrGetter
<
Arrayable
<
E
>>,
listener
:
MaybeRef
<
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
:
MaybeRefOrGetter
<
Arrayable
<
E
>>,
listener
:
MaybeRef
<
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 */ export declare function
useEventListener
<
E
extends keyof DocumentEventMap>(
target
: Document,
event
:
MaybeRefOrGetter
<
Arrayable
<
E
>>,
listener
:
MaybeRef
<
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 ShadowRoot target * * @see https://vueuse.org/useEventListener */ export declare function
useEventListener
<
E
extends keyof ShadowRootEventMap>(
target
:
MaybeRefOrGetter
<
Arrayable
<ShadowRoot> | null | undefined>,
event
:
MaybeRefOrGetter
<
Arrayable
<
E
>>,
listener
:
MaybeRef
<
Arrayable
<(
this
: ShadowRoot,
ev
: ShadowRootEventMap[
E
]) => any>
>,
options
?:
MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
):
Fn
/** * Register using addEventListener on mounted, and removeEventListener automatically on unmounted. * * Overload 5: Explicitly HTMLElement target * * @see https://vueuse.org/useEventListener */ export declare function
useEventListener
<
E
extends keyof HTMLElementEventMap>(
target
:
MaybeRefOrGetter
<
Arrayable
<HTMLElement> | null | undefined>,
event
:
MaybeRefOrGetter
<
Arrayable
<
E
>>,
listener
:
MaybeRef
<(
this
: HTMLElement,
ev
: HTMLElementEventMap[
E
]) => any>,
options
?:
MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
):
Fn
/** * Register using addEventListener on mounted, and removeEventListener automatically on unmounted. * * Overload 6: Custom event target with event type infer * * @see https://vueuse.org/useEventListener */ export declare function
useEventListener
<
Names
extends string,
EventType
= Event,
>(
target
:
MaybeRefOrGetter
<
Arrayable
<
InferEventTarget
<
Names
>> | null | undefined
>,
event
:
MaybeRefOrGetter
<
Arrayable
<
Names
>>,
listener
:
MaybeRef
<
Arrayable
<
GeneralEventListener
<
EventType
>>>,
options
?:
MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
):
Fn
/** * Register using addEventListener on mounted, and removeEventListener automatically on unmounted. * * Overload 7: Custom event target fallback * * @see https://vueuse.org/useEventListener */ export declare function
useEventListener
<
EventType
= Event>(
target
:
MaybeRefOrGetter
<
Arrayable
<EventTarget> | null | undefined>,
event
:
MaybeRefOrGetter
<
Arrayable
<string>>,
listener
:
MaybeRef
<
Arrayable
<
GeneralEventListener
<
EventType
>>>,
options
?:
MaybeRefOrGetter
<boolean | AddEventListenerOptions>,
):
Fn

Source

SourceDocs

Contributors

Anthony Fu
Anthony Fu
IlyaL
丶远方
SerKo
Arthur Darkstone
Fernando Fernández
我想静静
Forrest Li
陪我去看海吧
Julien Le Coupanec
Michael J. Roberts
James Garbutt
vaakian X
sun0day
Alejandro Arevalo
Jelf
Alex Kozack
lstoeferle
Antério Vieira

Changelog

v13.4.0 on
6f565 - fix: improve types (#4787)
v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
v12.5.0 on
caf08 - feat: make all parameters arrayable and reactive (#4486)
v12.3.0 on
021d0 - feat(toArray): new utility function (#4432)
59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's native
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v11.0.0-beta.2 on
edab6 - fix: event target can be an empty ref/getter (#4014)
v10.8.0 on
a086e - fix: stricter types
v10.4.1 on
3ef59 - fix: immutable options on removal, close #2825 (#3346)
v10.3.0 on
4f414 - fix: improved useEventListener overload (#3246)
v10.0.0-beta.5 on
cb644 - refactor!: remove isFunction and isString utils
v10.0.0-beta.4 on
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue

Released under the MIT License.

Build faster with AI
New Masterclass to help you leverage AI in your Vue workflow
Get Early Access