{"id":11701,"library":"react-event-listener","title":"React Event Listener","description":"react-event-listener is a lightweight React component that offers a declarative way to manage global DOM event listeners, specifically targeting `window` and `document`. It leverages React's component lifecycle to automatically bind and unbind events, preventing common memory leaks and simplifying event management for global scopes. The current stable version is `0.6.7`, and releases are infrequent, primarily focused on maintenance and compatibility updates rather than new features, indicating a mature and stable library. A key differentiator is its `withOptions` utility, allowing developers to configure standard `addEventListener` options like `passive` and `capture` declaratively. It aims to solve the problem of imperatively adding and removing global event listeners by integrating them seamlessly into the React component tree.","status":"maintenance","version":"0.6.7","language":"javascript","source_language":"en","source_url":"https://github.com/oliviertassinari/react-event-listener","tags":["javascript","react","event","listener","binding"],"install":[{"cmd":"npm install react-event-listener","lang":"bash","label":"npm"},{"cmd":"yarn add react-event-listener","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-event-listener","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for React component functionality.","package":"react","optional":false}],"imports":[{"note":"EventListener is the default export of the package.","wrong":"const EventListener = require('react-event-listener');","symbol":"EventListener","correct":"import EventListener from 'react-event-listener';"},{"note":"withOptions is a named export used to configure standard EventListener options like passive or capture.","wrong":"import withOptions from 'react-event-listener';","symbol":"withOptions","correct":"import { withOptions } from 'react-event-listener';"},{"note":"While not an import, the 'target' prop can be a string ('window', 'document') or a direct DOM element, which is a key usage pattern.","symbol":"Target Type","correct":"import EventListener from 'react-event-listener';"}],"quickstart":{"code":"import React, { Component } from 'react';\nimport EventListener, { withOptions } from 'react-event-listener';\nimport ReactDOM from 'react-dom';\n\nclass MyComponent extends Component {\n  handleResize = () => {\n    console.log('Window resized!');\n  };\n\n  handleScroll = () => {\n    // This will only log if scroll is detected due to passive: true\n    console.log('Window scrolled (passive)!');\n  };\n\n  handleKeyDown = (event) => {\n    if (event.key === 'Escape') {\n      console.log('Escape key pressed on document (capture)!');\n    }\n  };\n\n  render() {\n    return (\n      <div>\n        <h1>Global Event Listener Example</h1>\n        <p>Open your console and try resizing the window, scrolling, or pressing 'Escape'.</p>\n        <div style={{ height: '200vh', background: 'lightgray', padding: '20px' }}>\n          Scrollable content to trigger window scroll.\n          <p>This div ensures the page is tall enough to scroll.</p>\n        </div>\n        <EventListener\n          target=\"window\"\n          onResize={this.handleResize}\n          onScroll={withOptions(this.handleScroll, { passive: true, capture: false })}\n        />\n        <EventListener target={document} onKeyDownCapture={this.handleKeyDown} />\n      </div>\n    );\n  }\n}\n\n// Assuming a root element with id 'root' exists in your HTML\nReactDOM.render(<MyComponent />, document.getElementById('root'));\n","lang":"javascript","description":"This example demonstrates how to use EventListener to bind to global 'window' resize and scroll events, and 'document' keydown events, including the use of `withOptions` for event configuration."},"warnings":[{"fix":"Define event handler methods as class properties (as shown in the quickstart) or use `useCallback` hook in functional components to ensure stable function references across renders, preventing unnecessary re-bindings and performance issues.","message":"Avoid using inline functions for event listeners passed to EventListener components.","severity":"gotcha","affected_versions":">=0.6.0"},{"fix":"Conditionally render the `EventListener` component only on the client-side, or ensure the `target` prop is a string ('window', 'document') which the library handles gracefully on the server, by doing nothing.","message":"When performing Server-Side Rendering (SSR), `window` and `document` objects are not available.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For testing global event listeners, use native DOM event dispatching methods such as `document.dispatchEvent(new Event('event-name'))` or `window.dispatchEvent(new Event('event-name'))` to accurately simulate global events.","cause":"React's `TestUtils.Simulate` methods only simulate events on the component itself and do not propagate to global DOM elements like `window` or `document`.","error":"React TestUtils.Simulate.event() does not bubble up to window or document."}],"ecosystem":"npm"}