![\"usefy](\"https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png\"){kind=logo}
\n\n \n
\n A React hook for adding event listeners to DOM elements with automatic cleanup\n
\n\n\n \n ![\"npm](\"https://img.shields.io/npm/v/@usefy/use-event-listener.svg?style=flat-square&color=007acc\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/@usefy/use-event-listener.svg?style=flat-square&color=007acc\")
\n \n \n ![\"bundle](\"https://img.shields.io/bundlephobia/minzip/@usefy/use-event-listener?style=flat-square&color=007acc\")
![\"license\"](\"https://img.shields.io/npm/l/@usefy/use-event-listener.svg?style=flat-square&color=007acc\")
\n \n
\n Installation ā¢\n Quick Start ā¢\n API Reference ā¢\n Examples ā¢\n License\n
\n\n\n \n š View Storybook Demo\n \n
\n\n---\n\n## Overview\n\n`@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.\n\n**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** ā a collection of production-ready React hooks designed for modern applications.\n\n### Why use-event-listener?\n\n- **Zero Dependencies** ā Pure React implementation with no external dependencies\n- **TypeScript First** ā Full type safety with automatic event type inference\n- **Multiple Targets** ā Support for window, document, HTMLElement, and RefObject\n- **Automatic Cleanup** ā Event listeners are removed on unmount\n- **Late-mounted Refs** ā Attaches automatically when a conditionally rendered `RefObject` target appears (or re-appears) after the initial render\n- **Handler Stability** ā No re-registration when handler changes\n- **Conditional Activation** ā Enable/disable via the `enabled` option\n- **Performance Options** ā Support for `passive`, `capture`, and `once` options\n- **SSR Compatible** ā Works seamlessly with Next.js, Remix, and other SSR frameworks\n- **Well Tested** ā Comprehensive test coverage with Vitest\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm install @usefy/use-event-listener\n\n# yarn\nyarn add @usefy/use-event-listener\n\n# pnpm\npnpm add @usefy/use-event-listener\n```\n\n### Peer Dependencies\n\nThis package requires React 18 or 19:\n\n```json\n{\n \"peerDependencies\": {\n \"react\": \"^18.0.0 || ^19.0.0\"\n }\n}\n```\n\n---\n\n## Quick Start\n\n```tsx\nimport { useEventListener } from \"@usefy/use-event-listener\";\n\nfunction WindowResizeTracker() {\n const [size, setSize] = useState({ width: 0, height: 0 });\n\n useEventListener(\"resize\", () => {\n setSize({ width: window.innerWidth, height: window.innerHeight });\n });\n\n return (\n\n Built with care by the usefy team\n
\n","readmeFilename":"README.md"}