Neighbourhood Party Manager

    @use-it/event-listener
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.7 • Public • Published

    @use-it/event-listener

    A custom React Hook that provides a declarative useEventListener.

    npm version All Contributors

    This hook was inspired by Dan Abramov's blog post "Making setInterval Declarative with React Hooks".

    I needed a way to simplify the plumbing around adding and removing an event listener in a custom hook. That lead to a chain of tweets between Dan and myself.

    Installation

    $ npm i @use-it/event-listener

    or

    $ yarn add @use-it/event-listener

    Usage

    Here is a basic setup.

    useEventListener(eventName, handler, element, options);

    Parameters

    Here are the parameters that you can use. (* = optional)

    Parameter Description
    eventName The event name (string). Here is a list of common events.
    handler A function that will be called whenever eventName fires on element.
    element* An optional element to listen on. Defaults to global (i.e., window).
    options* An object { capture?: boolean, passive?: boolean, once?: boolean } to be passed to addEventListener. For advanced use cases. See MDN for details.

    Return

    This hook returns nothing.

    Example

    Let's look at some sample code. Suppose you would like to track the mouse position. You could subscribe to mouse move events with like this.

    const useMouseMove = () => {
      const [coords, setCoords] = useState([0, 0]);
    
      useEffect(() => {
        const handler = ({ clientX, clientY }) => {
          setCoords([clientX, clientY]);
        };
        window.addEventListener('mousemove', handler);
        return () => {
          window.removeEventListener('mousemove', handler);
        };
      }, []);
    
      return coords;
    };

    Here we're using useEffect to roll our own handler add/remove event listener.

    useEventListener abstracts this away. You only need to care about the event name and the handler function.

    const useMouseMove = () => {
      const [coords, setCoords] = useState([0, 0]);
    
      useEventListener('mousemove', ({ clientX, clientY }) => {
        setCoords([clientX, clientY]);
      });
    
      return coords;
    };

    Live demo

    You can view/edit the sample code above on CodeSandbox.

    Edit demo app on CodeSandbox

    License

    MIT Licensed

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Donavon West

    🚇 ⚠️ 💡 🤔 🚧 👀 🔧 💻

    Kevin Kipp

    💻

    Justin Hall

    💻 📖

    Jeow Li Huan

    👀

    Norman Rzepka

    🤔

    Beer van der Drift

    ⚠️ 💻

    clingsoft

    💻

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i @use-it/event-listener

    DownloadsWeekly Downloads

    99,155

    Version

    0.1.7

    License

    MIT

    Unpacked Size

    14.5 kB

    Total Files

    10

    Last publish

    Collaborators

    • donavon