@custom-react-hooks/use-event-listener

useEventListener Hook

The useEventListener hook is a custom React hook that simplifies the process of adding and removing event listeners in your React components. It handles the lifecycle of the event listener, ensuring it is cleaned up when the component unmounts or dependencies change.

Installation

Installing Only Current Hooks

npm install @custom-react-hooks/use-event-listener

or

yarn add @custom-react-hooks/use-event-listener

Installing All Hooks

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

Features

• Effortless Event Handling: Streamlines the process of adding and removing event listeners in React components, making it easier to handle user interactions and other events.

• Automatic Cleanup: Automatically cleans up event listeners when the component unmounts or dependencies change, preventing memory leaks and ensuring optimal performance.

• Support for Multiple Events: Capable of attaching listeners to multiple events simultaneously, making it versatile for handling various types of interactions within a single component.

• Flexible Element Targeting: Offers the ability to attach event listeners to specific DOM elements using a ref, or defaults to the global window object if no element is specified.

• Conditional Event Listening: Includes an optional condition parameter to dynamically attach or detach event listeners based on certain conditions, enhancing the hook's adaptability in different scenarios.

• Custom Event Handling Function: Allows for the specification of a custom handler function for each event, providing full control over the response to the triggered events.

• Option Customization: Supports both boolean and object options for event listeners, aligning with the standard addEventListener API and providing flexibility for more complex event handling requirements.

• Ref Management: Uses a ref to store the current handler function, ensuring that the most recent handler is used and preventing stale closures.

• Event Listener Abstraction: Abstracts the complexities of correctly attaching and detaching event listeners in React's lifecycle, allowing developers to focus on the core logic of their components.

• Versatility in Use: Suitable for a wide range of use cases, from handling user inputs like keyboard and mouse events to responding to browser and device events like resizing and orientation changes.

Usage

Here's an example of how to use the useEventListener hook in a component:

import { useEventListener } from '@custom-react-hooks/all';

const EventListenerComponent = () => {
  const [count, setCount] = useState(0);

  const handleKeyDown = (event) => {
    if (event.key === 'ArrowRight') {
      setCount((prevCount) => prevCount + 1);
    } else if (event.key === 'ArrowLeft') {
      setCount((prevCount) => prevCount - 1);
    }
  };

  useEventListener('keydown', handleKeyDown);

  const getColor = () => {
    if (count < 0) return '#ff5868';
    if (count > 0) return '#00989a';
    return '#f9f871';
  };

  return (
    <div>
      <h2>Press the Arrow Left/Right keys to change the counter.</h2>
      <p>(If is not working, click me!)</p>
      <p>
        Counter: <span style={{ color: getColor() }}>{count}</span>
      </p>
    </div>
  );
};

export default EventListenerComponent;

In this component, useEventListener is used to listen for keydown events on the div element, and the state is updated with the last key pressed.

API Reference

Parameters

• eventName (string | string[]): The name of the event to listen to, or an array of event names.
• handler (function): The function to be called when the event is triggered.
• element (RefObject, optional): The ref object pointing to the DOM element to which the event listener will be attached. If not provided, the event listener will be attached to the window object.
• options (boolean | AddEventListenerOptions, optional): Options to pass to the event listener.
• condition (boolean, optional): A boolean value to conditionally attach or detach the event listener.

Use Cases

Let's explore the use cases for each of the four additional hooks you've provided:

1. useEventListener

• Custom Interactions: Capture custom user interactions like keyboard shortcuts or mouse movements.
• Tracking User Behavior: Monitor events for analytics, like clicks or page visibility changes.
• Interactive Components: Enhance components with interactive features, like drag-and-drop or hover effects.
• Window or Document Events: Listen to window resize, scroll, or focus events to adjust UI accordingly.
• Device Capabilities: Detect device capabilities, such as orientation change or network status updates.

Notes

• Ensure the element referenced by element is mounted when the hook is called.
• The hook is versatile and can be used for various events and elements within a React application.

Contributing

Your contributions to the development and enhancement of this hook are welcome! Feel free to submit issues or pull requests to the repository.