useEventListener

React version of `addEventListener`, optimized for performance and memory usage.

Installation

npm install @1hook/use-event-listener

Usage

import { useEventListener } from '@1hook/use-event-listener'

Attach an event listener to the target.

useEventListener(target, 'click', () => console.log('click'))

Target a DOM Element

You can use useEventListener to attach event listeners to specific DOM elements.

Using a ref:

function MyComponent() {
  const ref = useRef<HTMLDivElement | null>(null)

  useEventListener(ref, 'scroll', (e) => console.log('scroll'))

  return <div ref={ref} />
}

Using a stateful element:

function MyComponent() {
  const [target, setTarget] = useState<HTMLDivElement | null>(null)

  useEventListener(target, 'scroll', (e) => console.log('scroll'))

  return <div ref={setTarget} />
}

Using querySelector:

function MyComponent() {
  const target = document.querySelector('body > .scrollable')

  useEventListener(target, 'scroll', (e) => console.log('scroll'))

  return <div />
}

Target the window / document

For single-page applications (SPAs), you can directly use the window or document object:

useEventListener(window, 'click', (e) => console.log(e.target))

With SSR, you need to check if the code runs on the server before accessing the window object:

import { isServer } from '@1hook/use-event-listener'

useEventListener(!isServer && window, 'click', (e) => console.log(e.target))

Trigger the listener manually

This example shows how to listen for the 'mousemove' & 'mouseup' global events only after the 'mousedown' event has occurred.

useEventListener(document.getElementById('target'), 'mousedown', (e) => {
  // Activate mousemove and mouseup listeners after mousedown occurs
  mousemoveListener.add()
  mouseupListener.add()
})

const mousemoveListener = useEventListener(
  document,
  'mousemove',
  (e) => console.log('Mouse Move'),
  { autoListen: false }, // Do not attach the listener automatically
)

const mouseupListener = useEventListener(
  document,
  'mouseup',
  (e) => {
    // Remove both listeners after mouseup event
    mousemoveListener.remove()
    mouseupListener.remove()
  },
  { autoListen: false }, // Do not attach the listener automatically
)

API Reference

Parameters

The useEventListener hook accepts four arguments:

Argument	Description
(1) `target`	The element to attach the listener to.
(2) `type`	See MDN Docs
(3) `listener`	See MDN Docs
(4) `options`	Event listener options (see MDN docs) with the following differences: - `autoListen`: if `false` the listener is not attached automatically on mount. - `signal` is omitted

UseEventListenerReturn

What `useEventListener` returns

Prop	Type	Default
`remove`	`() => void`	-
`add`	`() => void`	-