React offers a range of powerful built-in hooks for various use cases. However, there are times when a custom hook tailored to a specific purpose is invaluable. In this series, we'll explore some of the most useful custom hooks I employ in every project. In this inaugural installment, we'll delve into the useEventListeneruseEventListener hook, both using it and creating it from scratch.

Starting from Scratch

Listening for events in JavaScript typically involves adding an event listener to the target responsible for generating those events. For instance, to listen for events on the window, you'd use pure JavaScript:

window.addEventListener('keydown', (e) => {
  console.log('Key has been pressed!');
});

window.addEventListener('keydown', (e) => {
  console.log('Key has been pressed!');
});

However, directly adding event listeners like this within a React component is discouraged due to potential pitfalls. These include the risk of adding multiple listeners for the same event and neglecting to remove listeners when a component is unmounted.

To address this, we can leverage the built-in useEffectuseEffect hook. This hook allows us to synchronize our component with external systems, such as the windowwindow object. By utilizing it, we ensure that our listener is added only once when the component is mounted, and it is properly removed when the component is unmounted.

import { useEffect } from 'react';
 
const App = () => {
  useEffect(() => {
    const callback = (e) => {
      console.log('Key has been pressed!');
    };
    window.addEventListener('keydown', callback);
 
    return () => window.removeEventListener('keydown', callback);
  }, []);
 
  return <div>Hello World!</div>;
};

import { useEffect } from 'react';
 
const App = () => {
  useEffect(() => {
    const callback = (e) => {
      console.log('Key has been pressed!');
    };
    window.addEventListener('keydown', callback);
 
    return () => window.removeEventListener('keydown', callback);
  }, []);
 
  return <div>Hello World!</div>;
};

While this approach is effective, it may lead to repetitive code across components or even within the same component if multiple events need to be listened for. Custom hooks come to our rescue!

Creating our Own Custom Hook

A custom hook allows us to extract and encapsulate custom logic for reuse. It's convention to name hooks starting with useuse. Let's create our useEventListeneruseEventListener hook, designed to simplify event handling.

import { useEffect, useRef } from 'react';
 
export const useEventListener = (targetElement, type, listener) => {
  const listenerRef = useRef(listener);
 
  useEffect(() => {
    listenerRef.current = listener;
  }, [listener]);
 
  useEffect(() => {
    if (targetElement === null) {
      return;
    }
 
    const eventListener = (e) => listenerRef.current(e);
    targetElement.addEventListener(type, eventListener);
 
    return () => targetElement.removeEventListener(type, eventListener);
  }, [targetElement, type]);
};

import { useEffect, useRef } from 'react';
 
export const useEventListener = (targetElement, type, listener) => {
  const listenerRef = useRef(listener);
 
  useEffect(() => {
    listenerRef.current = listener;
  }, [listener]);
 
  useEffect(() => {
    if (targetElement === null) {
      return;
    }
 
    const eventListener = (e) => listenerRef.current(e);
    targetElement.addEventListener(type, eventListener);
 
    return () => targetElement.removeEventListener(type, eventListener);
  }, [targetElement, type]);
};

How to Use it

To use our custom hook, simply import it and call it within your component. Provide the necessary parameters, such as the target element, event type, and the callback function.

import { useEventListener } from 'src/hooks/useEventListener'; // or specify your hook's path
 
const App = () => {
  useEventListener(window, 'keydown', (e) => {
    console.log('Key has been pressed!');
  });
 
  return <div>Hello World!</div>;
};

import { useEventListener } from 'src/hooks/useEventListener'; // or specify your hook's path
 
const App = () => {
  useEventListener(window, 'keydown', (e) => {
    console.log('Key has been pressed!');
  });
 
  return <div>Hello World!</div>;
};

Now, your code is clean, concise, and reusable!

Full Source Code

As will always be the case, the full source code for the custom hook we created in this post is available below and you can also see examples of it being used in action in the GitHub Repository for the blog you are reading right now!

import { useEffect, useRef } from 'react';
 
type EventMap = HTMLElementEventMap & WindowEventMap & DocumentEventMap & MediaQueryListEventMap;
 
export const useEventListener = <K extends keyof EventMap>(
  targetElement: HTMLElement | Window | Document | MediaQueryList | null,
  type: K,
  listener: (event: EventMap[K]) => void
) => {
  const listenerRef = useRef(listener);
 
  useEffect(() => {
    listenerRef.current = listener;
  }, [listener]);
 
  useEffect(() => {
    if (targetElement === null) {
      return;
    }
 
    const eventListener = (e: Event) => listenerRef.current(e as EventMap[K]);
    targetElement.addEventListener(type, eventListener);
 
    return () => targetElement.removeEventListener(type, eventListener);
  }, [type, targetElement]);
};

import { useEffect, useRef } from 'react';
 
type EventMap = HTMLElementEventMap & WindowEventMap & DocumentEventMap & MediaQueryListEventMap;
 
export const useEventListener = <K extends keyof EventMap>(
  targetElement: HTMLElement | Window | Document | MediaQueryList | null,
  type: K,
  listener: (event: EventMap[K]) => void
) => {
  const listenerRef = useRef(listener);
 
  useEffect(() => {
    listenerRef.current = listener;
  }, [listener]);
 
  useEffect(() => {
    if (targetElement === null) {
      return;
    }
 
    const eventListener = (e: Event) => listenerRef.current(e as EventMap[K]);
    targetElement.addEventListener(type, eventListener);
 
    return () => targetElement.removeEventListener(type, eventListener);
  }, [type, targetElement]);
};