raddix

useEventListener

The useEventListener hook allows you to add event listeners to a DOM element using a declarative syntax.

Features

  • Automatically removes the event listener when the component unmounts.
  • Supports a ref object as a target element.
  • You can specify event options such as capture, once, and passive.
  • Full TypeScript support for event type.

Installation

Install the custom hook from your command line.

npm i @raddix/use-event-listener

Usage

Add an event to the window object

In this example, the handle function will be called when the click event is triggered on the window object.

By default, the event listener will be added to the global window object. Therefore, it is not necessary to specify the target object.

import { useEventListener } from '@raddix/use-event-listener';
const Component = () => {
const handle = () => {
// Do something
};
useEventListener('click', handle);
};

Add an event to a element

In this example, the handle function will be called when the mousemove event is triggered on the div element.

To add an event listener to a element, you need to pass its ref to the target option.

import { useState, useRef } from 'react';
import { useEventListener } from '@raddix/use-event-listener';
const Component = () => {
const [coords, setCoords] = useState([0, 0]);
const ref = useRef<HTMLDivElement>(null);
useEventListener('mousemove', ({ offsetX, offsetY }) => {
setCoords([offsetX, offsetY]);
}, { target: ref });
return <div ref={ref}>...</div>;
};

API

Parameters

ParameterDescriptionRequiredType
typeThe event type to listen for. It can be any event type supported by the browser.Yesstring
handlerThe function that is called when the event is triggered.Yesfunction
optionsThe options object.Noobject

Configurable options

OptionDescriptionRequiredType
targetThe target element to add the event listener to. It can be a ref object or a DOM element.NoRefObject | HTMLElement
captureA Boolean indicating that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree.Noboolean
onceA Boolean indicating that the listener should be invoked at most once after being added. If true, the listener would be automatically removed when invoked.Noboolean
passiveA Boolean indicating that the listener will never call preventDefault(). If it does, the user agent should ignore it and generate a console warning.Noboolean