---
## Overview
`@usefy/use-event-listener` provides a simple way to add event listeners to DOM elements with automatic cleanup on unmount. It supports window, document, HTMLElement, and RefObject targets with full TypeScript type inference.
**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
### Why use-event-listener?
- **Zero Dependencies** — Pure React implementation with no external dependencies
- **TypeScript First** — Full type safety with automatic event type inference
- **Multiple Targets** — Support for window, document, HTMLElement, and RefObject
- **Automatic Cleanup** — Event listeners are removed on unmount
- **Late-mounted Refs** — Attaches automatically when a conditionally rendered `RefObject` target appears (or re-appears) after the initial render
- **Handler Stability** — No re-registration when handler changes
- **Conditional Activation** — Enable/disable via the `enabled` option
- **Performance Options** — Support for `passive`, `capture`, and `once` options
- **SSR Compatible** — Works seamlessly with Next.js, Remix, and other SSR frameworks
- **Well Tested** — Comprehensive test coverage with Vitest
---
## Installation
```bash
# npm
npm install @usefy/use-event-listener
# yarn
yarn add @usefy/use-event-listener
# pnpm
pnpm add @usefy/use-event-listener
```
### Peer Dependencies
This package requires React 18 or 19:
```json
{
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0"
}
}
```
---
## Quick Start
```tsx
import { useEventListener } from "@usefy/use-event-listener";
function WindowResizeTracker() {
const [size, setSize] = useState({ width: 0, height: 0 });
useEventListener("resize", () => {
setSize({ width: window.innerWidth, height: window.innerHeight });
});
return (
Window size: {size.width} × {size.height}
);
}
```
---
## API Reference
### `useEventListener(eventName, handler, element?, options?)`
A hook that adds an event listener to the specified target.
#### Parameters
| Parameter | Type | Description |
| ----------- | ------------------------- | ------------------------------------------------------ |
| `eventName` | `string` | The event type to listen for (e.g., "click", "resize") |
| `handler` | `(event: Event) => void` | Callback function called when the event fires |
| `element` | `EventTargetType` | Target element (defaults to window) |
| `options` | `UseEventListenerOptions` | Configuration options |
#### Options
| Option | Type | Default | Description |
| --------- | --------- | ----------- | ------------------------------------------ |
| `enabled` | `boolean` | `true` | Whether the event listener is active |
| `capture` | `boolean` | `false` | Use event capture phase instead of bubble |
| `passive` | `boolean` | `undefined` | Use passive event listener for performance |
| `once` | `boolean` | `false` | Handler is invoked once and then removed |
#### Supported Target Types
```typescript
type EventTargetType =
| Window // window object
| Document // document object
| HTMLElement // any HTML element
| React.RefObject // React ref
| null // no listener
| undefined; // defaults to window
```
#### Returns
`void`
---
## Examples
### Window Events (Default)
When no element is provided, events are attached to the window:
```tsx
import { useEventListener } from "@usefy/use-event-listener";
function ResizeHandler() {
useEventListener("resize", (e) => {
console.log("Window resized:", window.innerWidth, window.innerHeight);
});
return
