{"_id":"@aniruddha1806/use-event-listener","_rev":"4-28187c3e8f7a4eb31b09defc06788c15","name":"@aniruddha1806/use-event-listener","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@aniruddha1806/use-event-listener","version":"1.0.0","keywords":["react","hooks","event-listener","typescript","dom","events"],"author":{"name":"Your Name"},"license":"MIT","_id":"@aniruddha1806/use-event-listener@1.0.0","maintainers":[{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"}],"dist":{"shasum":"4139e2e09a820575dcc46e03450d51a39bcdf73e","tarball":"https://registry.npmjs.org/@aniruddha1806/use-event-listener/-/use-event-listener-1.0.0.tgz","fileCount":6,"integrity":"sha512-FN9XRX+0w+jVu2Z929fwjPKoBYTRzFX8qH7+LM22q2p6S3eGZpFHYpz7YKmEllheMW61dGbBkWFb4e8vVXpwlQ==","signatures":[{"sig":"MEYCIQC3oQqS0y399PzR92WjBFLRT6IU7N4Q8t062OpVzHgYPAIhAMoHuqwpqlpj2eIp1Og1nRVuKBt2oEG09CA+7lOepEur","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":8742},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.esm.js","scripts":{"lint":"eslint src/**/*.ts","test":"jest","build":"rollup -c","prepublishOnly":"npm run build"},"_npmUser":{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"},"_npmVersion":"10.9.1","description":"A flexible, type-safe React hook for managing event listeners with automatic cleanup","directories":{},"_nodeVersion":"20.14.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^28.1.1","react":"^18.1.0","tslib":"^2.4.0","eslint":"^8.17.0","rollup":"^2.75.6","ts-jest":"^28.0.4","react-dom":"^18.1.0","typescript":"^4.7.3","@types/jest":"^28.1.1","@types/react":"^18.0.12","rollup-plugin-terser":"^7.0.2","@rollup/plugin-commonjs":"^22.0.0","@rollup/plugin-typescript":"^8.3.2","@rollup/plugin-node-resolve":"^13.3.0","@testing-library/react-hooks":"^8.0.0","rollup-plugin-peer-deps-external":"^2.2.4"},"peerDependencies":{"react":">=16.8.0"},"_npmOperationalInternal":{"tmp":"tmp/use-event-listener_1.0.0_1744367612773_0.32202112832844176","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aniruddha1806/use-event-listener","version":"1.0.1","keywords":["react","hooks","event-listener","typescript","dom","events"],"author":{"name":"Your Name"},"license":"MIT","_id":"@aniruddha1806/use-event-listener@1.0.1","maintainers":[{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"}],"dist":{"shasum":"3005276dc93c0831e1204ca1d461a97d2e7366de","tarball":"https://registry.npmjs.org/@aniruddha1806/use-event-listener/-/use-event-listener-1.0.1.tgz","fileCount":6,"integrity":"sha512-zJ61FuYedBskTPuSRED3HfmaLGD1043HG8/pN5/oha42DTfWEM+jde3Sm/Bf8VNZCxtb82Yrf2uFnKDViRkQ1g==","signatures":[{"sig":"MEUCIQCq5XoAjbfor/VmcJmCaynCYxpICUrIaHeDgAJsn9ynXgIgWSzV6ZL3Dx+8KThNFuK58ijT8LLeqYOTkxPGmsluyQs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4173},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.esm.js","scripts":{"lint":"eslint src/**/*.ts","test":"jest","build":"rollup -c","prepublishOnly":"npm run build"},"_npmUser":{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"},"_npmVersion":"10.9.1","description":"A flexible, type-safe React hook for managing event listeners with automatic cleanup","directories":{},"_nodeVersion":"20.14.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^28.1.1","react":"^18.1.0","tslib":"^2.4.0","eslint":"^8.17.0","rollup":"^2.75.6","ts-jest":"^28.0.4","react-dom":"^18.1.0","typescript":"^4.7.3","@types/jest":"^28.1.1","@types/react":"^18.0.12","rollup-plugin-terser":"^7.0.2","@rollup/plugin-commonjs":"^22.0.0","@rollup/plugin-typescript":"^8.3.2","@rollup/plugin-node-resolve":"^13.3.0","@testing-library/react-hooks":"^8.0.0","rollup-plugin-peer-deps-external":"^2.2.4"},"peerDependencies":{"react":">=16.8.0"},"_npmOperationalInternal":{"tmp":"tmp/use-event-listener_1.0.1_1744368138134_0.9985833084944826","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aniruddha1806/use-event-listener","version":"1.0.2","keywords":["react","hooks","event-listener","typescript","dom","events"],"author":{"name":"Your Name"},"license":"MIT","_id":"@aniruddha1806/use-event-listener@1.0.2","maintainers":[{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"}],"dist":{"shasum":"fbace068b14fae97367e735ae82b7c64aaad8872","tarball":"https://registry.npmjs.org/@aniruddha1806/use-event-listener/-/use-event-listener-1.0.2.tgz","fileCount":6,"integrity":"sha512-oMhTHwCY0K7yLm4T3WyNVkJ4dQ9sS7ONhx+L3ic9m88y7mB2HDTgGbOCI1vLsznksplJPc9T8CjnIPoR74YcrQ==","signatures":[{"sig":"MEUCIHUtxxwVdF/d11w3+m7rdIp8yqTt3szULkxmSfLb0/+sAiEAoPcG+nfNl2cCk4EB2Z9sMIDhv3bBVQ99lD+6fR3xH+M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6002},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.esm.js","scripts":{"lint":"eslint src/**/*.ts","test":"jest","build":"rollup -c","prepublishOnly":"npm run build"},"_npmUser":{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"},"_npmVersion":"10.9.1","description":"A flexible, type-safe React hook for managing event listeners with automatic cleanup","directories":{},"_nodeVersion":"20.14.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^28.1.1","react":"^18.1.0","tslib":"^2.4.0","eslint":"^8.17.0","rollup":"^2.75.6","ts-jest":"^28.0.4","react-dom":"^18.1.0","typescript":"^4.7.3","@types/jest":"^28.1.1","@types/react":"^18.0.12","rollup-plugin-terser":"^7.0.2","@rollup/plugin-commonjs":"^22.0.0","@rollup/plugin-typescript":"^8.3.2","@rollup/plugin-node-resolve":"^13.3.0","@testing-library/react-hooks":"^8.0.0","rollup-plugin-peer-deps-external":"^2.2.4"},"peerDependencies":{"react":">=16.8.0"},"_npmOperationalInternal":{"tmp":"tmp/use-event-listener_1.0.2_1744369615609_0.9231837412707171","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aniruddha1806/use-event-listener","version":"1.0.3","description":"A flexible, type-safe React hook for managing event listeners with automatic cleanup","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"rollup -c","test":"jest","lint":"eslint src/**/*.ts","prepublishOnly":"npm run build"},"keywords":["react","hooks","event-listener","typescript","dom","events"],"author":{"name":"Your Name"},"license":"MIT","peerDependencies":{"react":">=16.8.0"},"devDependencies":{"@rollup/plugin-commonjs":"^22.0.0","@rollup/plugin-node-resolve":"^13.3.0","@rollup/plugin-typescript":"^8.3.2","@testing-library/react-hooks":"^8.0.0","@types/jest":"^28.1.1","@types/react":"^18.0.12","eslint":"^8.17.0","jest":"^28.1.1","react":"^18.1.0","react-dom":"^18.1.0","rollup":"^2.75.6","rollup-plugin-peer-deps-external":"^2.2.4","rollup-plugin-terser":"^7.0.2","ts-jest":"^28.0.4","tslib":"^2.4.0","typescript":"^4.7.3"},"_id":"@aniruddha1806/use-event-listener@1.0.3","_nodeVersion":"20.14.0","_npmVersion":"10.9.1","dist":{"integrity":"sha512-pqRqZhJ8fKaRUyaA/pQB8tv7roWr36ucDSXO5tv7oAVlTnhIgWfdx2h2sGvTrFoFYlJ2OSHU3Ao5T2vW2rki0A==","shasum":"2ee12806ed649b155479a0b9bdd4029625e9de5b","tarball":"https://registry.npmjs.org/@aniruddha1806/use-event-listener/-/use-event-listener-1.0.3.tgz","fileCount":7,"unpackedSize":18128,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDMcJR5uSRXWZ9JqdVLSRS0bWBUQ+mA/nCuBf5D6kPgrwIhAJ4QuOaVdFk85VjN446j1DYmiW84uS8z+NQSPSEYiwtd"}]},"_npmUser":{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"},"directories":{},"maintainers":[{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/use-event-listener_1.0.3_1749389711394_0.5801590887064174"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-11T10:33:32.661Z","modified":"2025-06-08T13:35:11.772Z","1.0.0":"2025-04-11T10:33:32.950Z","1.0.1":"2025-04-11T10:42:18.331Z","1.0.2":"2025-04-11T11:06:55.778Z","1.0.3":"2025-06-08T13:35:11.592Z"},"author":{"name":"Your Name"},"license":"MIT","keywords":["react","hooks","event-listener","typescript","dom","events"],"description":"A flexible, type-safe React hook for managing event listeners with automatic cleanup","maintainers":[{"name":"aniruddha1806","email":"aniruddha.kulkarni1806@gmail.com"}],"readme":"# React useEventListener Hook\r\n\r\nA type-safe, versatile event listener hook for React applications with TypeScript support. Easily attach event listeners to any DOM element, window, or document with proper cleanup and type safety.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @aniruddha1806/use-event-listener\r\n```\r\n\r\n## Features\r\n\r\n- ๐ŸŽฏ TypeScript support with full type definitions for all event types\r\n- ๐ŸŒ Works with Window, Document, and any HTML Element\r\n- ๐Ÿ”„ Supports both direct elements and React refs\r\n- ๐Ÿงน Automatic cleanup on unmount to prevent memory leaks\r\n- โš ๏ธ Development mode warnings for common mistakes\r\n- ๐Ÿ›ก๏ธ Type-safe event handling with proper event types\r\n- ๐Ÿ“ฆ Tiny footprint with zero dependencies\r\n- ๐Ÿ” Preserves the original listener reference between renders\r\n\r\n## Quick Start\r\n\r\n```jsx\r\nimport { useRef } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction App() {\r\n // Listen for window events\r\n useEventListener(window, 'resize', () => {\r\n console.log('Window resized!');\r\n });\r\n \r\n // Listen for document events\r\n useEventListener(document, 'visibilitychange', () => {\r\n console.log('Tab visibility changed!');\r\n });\r\n \r\n // Listen for element events using a ref\r\n const buttonRef = useRef(null);\r\n useEventListener(buttonRef, 'click', () => {\r\n console.log('Button clicked!');\r\n });\r\n \r\n return (\r\n
\r\n

useEventListener Example

\r\n \r\n
\r\n );\r\n}\r\n```\r\n\r\n## API\r\n\r\n### Parameters\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `target` | `Window \\| Document \\| HTMLElement \\| RefObject \\| Element \\| RefObject` | The event target |\r\n| `type` | `string` | The event type (e.g., 'click', 'resize') |\r\n| `listener` | `(event: Event) => void` | The event callback function |\r\n| `options` | `boolean \\| AddEventListenerOptions` | Optional event listener options |\r\n\r\n### Returns\r\n\r\n`void` - This hook doesn't return anything.\r\n\r\n## Examples\r\n\r\n### Window Event Listeners\r\n\r\nListen for global window events:\r\n\r\n```jsx\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction WindowEvents() {\r\n // Track window size\r\n const [windowSize, setWindowSize] = useState({\r\n width: window.innerWidth,\r\n height: window.innerHeight,\r\n });\r\n \r\n // Update dimensions on window resize\r\n useEventListener(window, 'resize', () => {\r\n setWindowSize({\r\n width: window.innerWidth,\r\n height: window.innerHeight,\r\n });\r\n });\r\n \r\n // Track online status\r\n const [isOnline, setIsOnline] = useState(navigator.onLine);\r\n \r\n useEventListener(window, 'online', () => setIsOnline(true));\r\n useEventListener(window, 'offline', () => setIsOnline(false));\r\n \r\n return (\r\n
\r\n

Window Size

\r\n

Width: {windowSize.width}px

\r\n

Height: {windowSize.height}px

\r\n \r\n

Network Status

\r\n

You are {isOnline ? 'online' : 'offline'}

\r\n
\r\n );\r\n}\r\n```\r\n\r\n### Document Event Listeners\r\n\r\nListen for document-level events:\r\n\r\n```jsx\r\nimport { useState } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction KeyboardShortcuts() {\r\n const [lastKey, setLastKey] = useState('');\r\n const [isFullScreen, setIsFullScreen] = useState(false);\r\n \r\n // Track keyboard shortcuts\r\n useEventListener(document, 'keydown', (event) => {\r\n setLastKey(event.key);\r\n \r\n // Handle keyboard shortcuts\r\n if (event.key === 'F' && event.ctrlKey) {\r\n event.preventDefault();\r\n toggleFullScreen();\r\n }\r\n });\r\n \r\n // Track document visibility\r\n useEventListener(document, 'visibilitychange', () => {\r\n console.log('Document visibility:', document.visibilityState);\r\n });\r\n \r\n const toggleFullScreen = () => {\r\n if (!document.fullscreenElement) {\r\n document.documentElement.requestFullscreen();\r\n setIsFullScreen(true);\r\n } else {\r\n document.exitFullscreen();\r\n setIsFullScreen(false);\r\n }\r\n };\r\n \r\n return (\r\n
\r\n

Keyboard Shortcuts

\r\n

Last key pressed: {lastKey || 'None'}

\r\n

Press Ctrl+F to toggle fullscreen

\r\n

Fullscreen: {isFullScreen ? 'Yes' : 'No'}

\r\n
\r\n );\r\n}\r\n```\r\n\r\n### Element Event Listeners with Refs\r\n\r\nListen for events on specific DOM elements using refs:\r\n\r\n```jsx\r\nimport { useRef, useState } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction DragAndDrop() {\r\n const [position, setPosition] = useState({ x: 0, y: 0 });\r\n const [isDragging, setIsDragging] = useState(false);\r\n const elementRef = useRef(null);\r\n \r\n // Handle mouse down on the element\r\n useEventListener(elementRef, 'mousedown', (event) => {\r\n setIsDragging(true);\r\n // Prevent text selection during drag\r\n event.preventDefault();\r\n });\r\n \r\n // Handle mouse move for dragging\r\n useEventListener(document, 'mousemove', (event) => {\r\n if (isDragging) {\r\n setPosition({\r\n x: event.clientX - 50, // Adjust for element size\r\n y: event.clientY - 50,\r\n });\r\n }\r\n });\r\n \r\n // Handle mouse up to stop dragging\r\n useEventListener(document, 'mouseup', () => {\r\n setIsDragging(false);\r\n });\r\n \r\n return (\r\n
\r\n

Drag and Drop

\r\n \r\n Drag me\r\n
\r\n \r\n );\r\n}\r\n```\r\n\r\n### Form Input Events\r\n\r\nHandle form input events:\r\n\r\n```jsx\r\nimport { useRef, useState } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction FormEvents() {\r\n const [inputValue, setInputValue] = useState('');\r\n const [isFocused, setIsFocused] = useState(false);\r\n const inputRef = useRef(null);\r\n \r\n // Handle input changes\r\n useEventListener(inputRef, 'input', (event) => {\r\n setInputValue(event.target.value);\r\n });\r\n \r\n // Handle focus events\r\n useEventListener(inputRef, 'focus', () => {\r\n setIsFocused(true);\r\n });\r\n \r\n // Handle blur events\r\n useEventListener(inputRef, 'blur', () => {\r\n setIsFocused(false);\r\n });\r\n \r\n return (\r\n
\r\n

Form Input Events

\r\n \r\n

Current value: {inputValue}

\r\n

Input is {isFocused ? 'focused' : 'not focused'}

\r\n
\r\n );\r\n}\r\n```\r\n\r\n### Passive Event Listeners\r\n\r\nUse passive event listeners for better scroll performance:\r\n\r\n```jsx\r\nimport { useRef } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction SmoothScroll() {\r\n const scrollContainerRef = useRef(null);\r\n \r\n // Use passive: true for better scroll performance\r\n useEventListener(\r\n scrollContainerRef,\r\n 'scroll',\r\n (event) => {\r\n console.log('Scroll position:', event.target.scrollTop);\r\n },\r\n { passive: true }\r\n );\r\n \r\n return (\r\n \r\n

Smooth Scrolling

\r\n {Array.from({ length: 50 }).map((_, index) => (\r\n

Scroll content item {index + 1}

\r\n ))}\r\n \r\n );\r\n}\r\n```\r\n\r\n## TypeScript Usage\r\n\r\nThe hook provides full TypeScript support with proper type inference:\r\n\r\n```typescript\r\nimport { useRef, useState } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\ninterface MousePosition {\r\n x: number;\r\n y: number;\r\n}\r\n\r\nfunction TypedEventExample() {\r\n // Properly typed state\r\n const [mousePosition, setMousePosition] = useState({ x: 0, y: 0 });\r\n const [clicks, setClicks] = useState(0);\r\n \r\n // Ref with proper HTML element type\r\n const buttonRef = useRef(null);\r\n \r\n // Window event with proper event type\r\n useEventListener(window, 'mousemove', (event: MouseEvent) => {\r\n setMousePosition({ x: event.clientX, y: event.clientY });\r\n });\r\n \r\n // Element event with proper event type\r\n useEventListener(buttonRef, 'click', (event: MouseEvent) => {\r\n // event is properly typed as MouseEvent\r\n setClicks(prev => prev + 1);\r\n console.log('Click position:', event.clientX, event.clientY);\r\n });\r\n \r\n // Document event with proper event type\r\n useEventListener(document, 'visibilitychange', (event: Event) => {\r\n console.log('Visibility changed:', document.visibilityState);\r\n });\r\n \r\n return (\r\n
\r\n

TypeScript Event Handling

\r\n

\r\n Mouse position: {mousePosition.x}, {mousePosition.y}\r\n

\r\n \r\n
\r\n );\r\n}\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Event Delegation\r\n\r\nImplement event delegation pattern:\r\n\r\n```jsx\r\nimport { useRef } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction EventDelegation() {\r\n const listRef = useRef(null);\r\n \r\n // Handle clicks on any list item through event delegation\r\n useEventListener(listRef, 'click', (event) => {\r\n // Find the closest list item that was clicked\r\n const listItem = event.target.closest('li');\r\n if (listItem) {\r\n console.log('List item clicked:', listItem.dataset.id);\r\n // Highlight the clicked item\r\n listItem.style.backgroundColor = '#f0f0f0';\r\n setTimeout(() => {\r\n listItem.style.backgroundColor = '';\r\n }, 300);\r\n }\r\n });\r\n \r\n return (\r\n
\r\n

Event Delegation

\r\n
    \r\n {Array.from({ length: 10 }).map((_, index) => (\r\n \r\n Item {index + 1}\r\n \r\n ))}\r\n
\r\n
\r\n );\r\n}\r\n```\r\n\r\n### Conditional Event Listeners\r\n\r\nAdd or remove event listeners conditionally:\r\n\r\n```jsx\r\nimport { useState } from 'react';\r\nimport useEventListener from '@aniruddha1806/use-event-listener';\r\n\r\nfunction ConditionalEvents() {\r\n const [isListening, setIsListening] = useState(false);\r\n const [events, setEvents] = useState([]);\r\n \r\n // Only add the event listener when isListening is true\r\n useEventListener(\r\n isListening ? window : null,\r\n 'mousemove',\r\n (event) => {\r\n setEvents((prev) => [\r\n ...prev.slice(-4),\r\n { x: event.clientX, y: event.clientY, time: new Date().toLocaleTimeString() },\r\n ]);\r\n },\r\n { passive: true }\r\n );\r\n \r\n return (\r\n
\r\n

Conditional Event Listener

\r\n \r\n

Status: {isListening ? 'Tracking mouse movement' : 'Not tracking'}

\r\n \r\n

Recent Mouse Events:

\r\n
    \r\n {events.map((event, index) => (\r\n
  • \r\n Position: ({event.x}, {event.y}) at {event.time}\r\n
    • \r\n ))}\r\n
\r\n
\r\n );\r\n}\r\n```\r\n\r\n```\r\n\r\n","readmeFilename":"README.md"}