Registry / web-framework / react-event-listener

react-event-listener

library0.6.7jsnpmunverified

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.

web-framework

npm install react-event-listener

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-EVENT-LISTEN

react-event-listener

web-frameworkjavascriptv0.6.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

EventListener

✓ import EventListener from 'react-event-listener';

✗ const EventListener = require('react-event-listener');

EventListener is the default export of the package.

withOptions

✓ import { withOptions } from 'react-event-listener';

✗ import withOptions from 'react-event-listener';

withOptions is a named export used to configure standard EventListener options like passive or capture.

Target Type

✓ import EventListener from 'react-event-listener';

While not an import, the 'target' prop can be a string ('window', 'document') or a direct DOM element, which is a key usage pattern.

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.

import React, { Component } from 'react'; import EventListener, { withOptions } from 'react-event-listener'; import ReactDOM from 'react-dom'; class MyComponent extends Component { handleResize = () => { console.log('Window resized!'); }; handleScroll = () => { // This will only log if scroll is detected due to passive: true console.log('Window scrolled (passive)!'); }; handleKeyDown = (event) => { if (event.key === 'Escape') { console.log('Escape key pressed on document (capture)!'); } }; render() { return ( <div> <h1>Global Event Listener Example</h1> <p>Open your console and try resizing the window, scrolling, or pressing 'Escape'.</p> <div style={{ height: '200vh', background: 'lightgray', padding: '20px' }}> Scrollable content to trigger window scroll. <p>This div ensures the page is tall enough to scroll.</p> </div> <EventListener target="window" onResize={this.handleResize} onScroll={withOptions(this.handleScroll, { passive: true, capture: false })} /> <EventListener target={document} onKeyDownCapture={this.handleKeyDown} /> </div> ); } } // Assuming a root element with id 'root' exists in your HTML ReactDOM.render(<MyComponent />, document.getElementById('root'));

Debug

Known issues

gotchaAvoid using inline functions for event listeners passed to EventListener components.

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.

affects: >=0.6.0

gotchaWhen performing Server-Side Rendering (SSR), `window` and `document` objects are not available.

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.

affects: *

Errors

Common errors & fixes

React TestUtils.Simulate.event() does not bubble up to window or document.

React's `TestUtils.Simulate` methods only simulate events on the component itself and do not propagate to global DOM elements like `window` or `document`.

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.

Upgrade

Version history

0.6.7latest on npm

Audit

Dependencies

reactrequiredRequired as a peer dependency for React component functionality.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/oliviertassinari/react-event-listener ↗

packagehttps://www.npmjs.com/package/react-event-listener ↗