event-listener

Attach an event listener to a reactive target and clean it up with the current reactive scope.


Package	`@vizejs/composable/event-listener`
Own the source	`vize lib pull composable:event-listener`
Runtime exports	`useEventListener`
Gzip budget	2048 B

Usage

import { useEventListener } from "@vizejs/composable/event-listener";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useEventListener`	events	experimental	safe	stable	caller, reactive-scope	web, server, worker, native, desktop, terminal	—	`tryOnScopeDispose`

API

`useEventListener`

Attach an event listener to a reactive target and clean it up with the current reactive scope. Missing targets are valid during server rendering: a null/undefined target keeps the listener detached until a concrete target appears, so no browser globals are required. The listener is re-attached whenever the reactive target changes and is removed when the owning reactive scope stops, when EventListenerControls.stop is called, or when the abort signal fires. Outside an active scope, teardown ownership stays with the caller, who must call stop explicitly. Errors thrown by a custom target's add/remove methods propagate to the active watcher run.

function useEventListener<Key extends keyof WindowEventMap>( target: MaybeRefOrGetter<Window | null | undefined>, event: Key, listener: (event: WindowEventMap[Key]) => void, options?: UseEventListenerOptions, ): EventListenerControls

`useEventListener`

function useEventListener<Key extends keyof DocumentEventMap>( target: MaybeRefOrGetter<Document | null | undefined>, event: Key, listener: (event: DocumentEventMap[Key]) => void, options?: UseEventListenerOptions, ): EventListenerControls

`useEventListener`

function useEventListener<Key extends keyof HTMLElementEventMap>( target: MaybeRefOrGetter<HTMLElement | null | undefined>, event: Key, listener: (event: HTMLElementEventMap[Key]) => void, options?: UseEventListenerOptions, ): EventListenerControls

`useEventListener`

function useEventListener( target: MaybeRefOrGetter<EventTarget | null | undefined>, event: string, listener: EventListener, options?: UseEventListenerOptions, ): EventListenerControls

`useEventListener`

function useEventListener( target: MaybeRefOrGetter<EventTarget | null | undefined>, event: string, listener: EventListener, options: UseEventListenerOptions = {}, ): EventListenerControls

Types

`UseEventListenerOptions`

Options for useEventListener.

Member	Type	Description
`capture`?	`boolean`	Invoke the listener during the capture phase.
`once`?	`boolean`	Stop listening after the first event.
`passive`?	`boolean`	Declare that the listener does not cancel the event's default action.
`signal`?	`AbortSignal`	Stop listening when this signal is aborted. An already-aborted signal prevents listening from ever starting.
`immediate`?	`boolean`	Start listening during composable creation.
`flush`?	`"pre" \| "post" \| "sync"`	Reactive target update timing.

`EventListenerControls`

Reactive controls returned by useEventListener.

Member	Type	Description
`isListening`	`Readonly<Ref<boolean>>`	Whether a concrete target currently owns the listener.
`start`	`() => boolean`	Begin listening.
`stop`	`() => void`	Stop listening. Repeated calls are safe.