useEventListener()

Import from

@gabreusi/hyrax/react

Size budget

≤ 450 B

Examples

Type-checked, not run

useEventListener(target, type, handler)

function useEventListener<K extends keyof WindowEventMap>(
   target: MaybeRef<Window>, 
   type: K, 
   handler: (event: WindowEventMap[K]) => void, 
   options?: ListenOptions
): void;

Defined in: react/useEventListener.ts:32

Listens to an event on the window for as long as the component is mounted.

The handler is read from the latest render, so it can use fresh props and state without a dependency array and without listening again. Changing type, the target or an option does listen again.

Type Parameters

Type Parameter
K extends keyof WindowEventMap

Parameters

Parameter	Type	Description
target	MaybeRef<Window>	The window, a ref to it, or null/undefined (nothing is listened to). On the server window does not exist: pass globalThis.window, which is undefined there.
type	K	The event name.
handler	(event: WindowEventMap[K]) => void	Called with the event.
options?	ListenOptions	A capture flag or addEventListener options. A new object every render is fine.

Returns

void

Example

import { useState } from "react";

function Width() {
  const [width, setWidth] = useState(0);
  useEventListener(window, "resize", () => setWidth(window.innerWidth));
  return <p>{width}px</p>;
}

useEventListener(target, type, handler)

function useEventListener<K extends keyof DocumentEventMap>(
   target: MaybeRef<Document>, 
   type: K, 
   handler: (event: DocumentEventMap[K]) => void, 
   options?: ListenOptions
): void;

Defined in: react/useEventListener.ts:58

Listens to an event on the document for as long as the component is mounted.

Type Parameters

Type Parameter
K extends keyof DocumentEventMap

Parameters

Parameter	Type	Description
target	MaybeRef<Document>	The document, a ref to it, or null/undefined. On the server pass globalThis.document.
type	K	The event name.
handler	(event: DocumentEventMap[K]) => void	Called with the event.
options?	ListenOptions	A capture flag or addEventListener options.

Returns

void

Example

import { useState } from "react";

function Visibility() {
  const [hidden, setHidden] = useState(false);
  useEventListener(document, "visibilitychange", () => setHidden(document.hidden));
  return <p>{hidden ? "Away" : "Here"}</p>;
}

useEventListener(target, type, handler)

function useEventListener<K extends keyof HTMLElementEventMap>(
   target: MaybeRef<HTMLElement>, 
   type: K, 
   handler: (event: HTMLElementEventMap[K]) => void, 
   options?: ListenOptions
): void;

Defined in: react/useEventListener.ts:87

Listens to an event on an element for as long as the component is mounted.

A ref is read when the effect runs, after the first render. An element that is rendered conditionally, and so appears later, is missed by a ref: keep it in state with a callback ref (<div ref={setNode}>) and pass the state instead.

Type Parameters

Type Parameter
K extends keyof HTMLElementEventMap

Parameters

Parameter	Type	Description
target	MaybeRef<HTMLElement>	The element, a ref to it, or null/undefined.
type	K	The event name.
handler	(event: HTMLElementEventMap[K]) => void	Called with the event.
options?	ListenOptions	A capture flag or addEventListener options.

Returns

void

Example

import { useRef } from "react";

function Clicker() {
  const button = useRef<HTMLButtonElement>(null);
  useEventListener(button, "click", (event) => console.log(event.clientX));
  return <button ref={button}>Click</button>;
}

useEventListener(target, type, handler)

function useEventListener(
   target: MaybeRef<EventTarget>, 
   type: string, 
   handler: (event: Event) => void, 
   options?: ListenOptions
): void;

Defined in: react/useEventListener.ts:109

Listens to an event on any EventTarget (an SVG element, an EventSource, your own bus).

Parameters

Parameter	Type	Description
target	MaybeRef<EventTarget>	The target, a ref to it, or null/undefined.
type	string	The event name.
handler	(event: Event) => void	Called with the event.
options?	ListenOptions	A capture flag or addEventListener options.

Returns

void

Example

function Bus({ bus }: { bus: EventTarget }) {
  useEventListener(bus, "message", (event) => console.log(event));
  return null;
}