Skip to main content

​
Overview

Registers a window event listener and automatically removes it when dependencies change or the component unmounts. This hook is ideal for global window events like resize, scroll, or custom events.

​
Function Signature

function useWindowEvent<K extends string>(
  type: K,
  listener: WindowEventListener<K>,
  options?: boolean | AddEventListenerOptions
): void

​
Type Definitions

type WindowEventListener<K extends string> = K extends keyof WindowEventMap
  ? (this: Window, ev: WindowEventMap[K]) => void
  : (this: Window, ev: CustomEvent) => void;

​
Parameters

​
type
K extends string
required
Window event name to subscribe to. Can be a standard window event like "resize", "scroll", "focus", or a custom event name.
​
listener
WindowEventListener<K>
required
Listener function called when the event fires. The function receives the event object as a parameter.
​
options
boolean | AddEventListenerOptions
Optional listener options passed to addEventListener, such as capture, once, or passive.

​
Return Value

This hook returns void. It manages the event listener internally and cleans up automatically.

​
Usage Example

import { useCallback, useState } from "react";
import { useWindowEvent } from "@kuzenbo/hooks";

function Example() {
  const [windowWidth, setWindowWidth] = useState(window.innerWidth);

  const handleResize = useCallback(() => {
    setWindowWidth(window.innerWidth);
  }, []);

  useWindowEvent("resize", handleResize);

  return (
    <div>
      <p>Current window width: {windowWidth}px</p>
    </div>
  );
}

​
Custom Events Example

import { useCallback } from "react";
import { useWindowEvent } from "@kuzenbo/hooks";

function Example() {
  const handleCustomEvent = useCallback((event: CustomEvent) => {
    console.log("Custom event received:", event.detail);
  }, []);

  useWindowEvent("my-custom-event", handleCustomEvent);

  return <div>Listening for custom events...</div>;
}

​
Features

  • Automatic cleanup on component unmount
  • Re-registers listener when dependencies change
  • Type-safe for standard window events
  • Supports custom events with CustomEvent type
  • Accepts all native addEventListener options

Build docs developers (and LLMs) love

Get started for freeTalk to us