@solid-primitives/event-listener

@solid-primitives/event-listener

A set of primitives that help with listening to DOM and Custom Events.

Non-reactive primitives:

• makeEventListener — Non-reactive primitive for adding event listeners that gets removed onCleanup.
• makeEventListenerStack — Creates a stack of event listeners, that will be automatically disposed on cleanup.

Reactive primitives:

• createEventListener — Reactive version of makeEventListener, that takes signal arguments to apply new listeners once changed.
• createEventSignal — Like createEventListener, but captured events are stored in a returned signal.
• createEventListenerMap — A helpful primitive that listens to a map of events. Handle them by individual callbacks.

Component global listeners:

• WindowEventListener — Listen to the window DOM Events, using a component.
• DocumentEventListener — Listen to the document DOM Events, using a component.

Callback Wrappers

• preventDefault — Wraps event handler with e.preventDefault() call.
• stopPropagation — Wraps event handler with e.stopPropagation() call.
• stopImmediatePropagation — Wraps event handler with e.stopImmediatePropagation() call.

Installation

npm install @solid-primitives/event-listener
# or
yarn add @solid-primitives/event-listener
# or
pnpm add @solid-primitives/event-listener

makeEventListener

Added id @2.0.0

Can be used to listen to DOM or Custom Events on window, document, or any EventTarget.

Event listener is automatically removed on root cleanup. The clear() function is also returned for calling it early.

How to use it

import { makeEventListener } from "@solid-primitives/event-listener";

const clear = makeEventListener(
  document.getElementById("myButton"),
  "mousemove",
  e => console.log("x:", e.pageX, "y:", e.pageY),
  { passive: true }
);

// to clear all of the event listeners
clear();

// when listening to element refs, call it inside onMount
let ref!: HTMLDivElement
onMount(() => {
  makeEventListener(ref, "click", e => {...}, { passive: true });
});

<div ref={ref} />;

Custom events

// you can provide your own event map type as well:
// fill both type generics for the best type support
makeEventListener<{ myCustomEvent: MyEvent; other: Event }, "myCustomEvent">(
  window,
  "myCustomEvent",
  () => console.log("yup!"),
);
// just don't use interfaces as EventMaps! (write them using `type` keyword)

makeEventListenerStack

Added id @2.0.0

Creates a stack of event listeners, that will be automatically disposed on cleanup.

How to use it

import { makeEventListenerStack } from "@solid-primitives/event-listener";

const [listen, clear] = makeEventListenerStack(target, { passive: true });

listen("mousemove", handleMouse);
listen("dragover", handleMouse);

// remove listener (will also happen on cleanup)
clear();

createEventListener

Reactive version of makeEventListener, that can take signal target and type arguments to apply new listeners once changed.

How to use it

import { createEventListener } from "@solid-primitives/event-listener";

// target element and event name can be reactive signals
const [ref, setRef] = createSignal<HTMLElement>();
const [type, setType] = createSignal("mousemove");
createEventListener(ref, type, e => {...});

// when using ref as a target, pass it in a function – function will be executed after mount
// or wrap the whole primitive in onMount
let ref;
createEventListener(() => ref, "mousemove", e => {});
<div ref={ref} />;

// it can also be used with any HTML Element if you can get a reference to it
createEventListener(
  document.getElementById("myButton"),
  "mousemove",
  e => console.log("x:", e.pageX, "y:", e.pageY),
  { passive: true }
);

Custom events

// you can provide your own event map type as well:
// fill both type generics for the best type support
createEventListener<{ myCustomEvent: MyEvent; other: Event }, "myCustomEvent">(
  window,
  "myCustomEvent",
  () => console.log("yup!"),
);
// just don't use interfaces as EventMaps! (write them using `type` keyword)

Removing event listeners manually

Since version @2.0.0 createEventListener and other reactive primitives aren't returning a clear() function, because of it's flawed behavior described in this issue.

Although there are still ways to remove attached event listeners:

• Changing reactive target or type arguments to an empty array.

const [type, setType] = createSignal<"click" | []>("click");
createEventListener(window, type, e => {...});
// remove listener:
setType([]);

• Wrapping usage of createEventListener primitive in Solid's createRoot or createBranch | createDisposable from "@solid-primitives/rootless".

import { createDisposable } from "@solid-primitives/rootless";

const clear = createDisposable(() => createEventListener(element, "click", e => {...}));
// remove listener:
clear();

Listening to multiple events

Added in @1.4.3

You can listen to multiple events with single createEventListener primitive.

createEventListener(el, ["mousemove", "mouseenter", "mouseleave"], e => {});

Ref factory (directive) usage

eventListener returns a ref callback. Pass the props as a tuple, or as an accessor to swap handlers on the fly.

import { eventListener } from "@solid-primitives/event-listener";

<button ref={eventListener(["click", () => console.log("Click")])}>Click!</button>;

// reactive props — the listener is re-attached when they change
<button ref={eventListener(() => ["click", handler()])}>Click!</button>;

createEventSignal

Like createEventListener, but events are handled with the returned signal, instead of with a callback.

How to use it

import { createEventSignal } from "@solid-primitives/event-listener";

// all arguments can be reactive signals
const lastEvent = createEventSignal(el, "mousemove", { passive: true });

createEffect(() => {
  console.log(lastEvent()?.x, lastEvent()?.y);
});

createEventListenerMap

A helpful primitive that listens to a map of events. Handle them by individual callbacks.

How to use it

import { createEventListenerMap } from "@solid-primitives/event-listener";

createEventListenerMap(element, {
  mousemove: mouseHandler,
  mouseenter: e => {},
  touchend: touchHandler,
});

// both target can be reactive:
const [target, setTarget] = createSignal(document.getElementById("abc"));
createEventListenerMap(
  target,
  {
    mousemove: e => {},
    touchstart: e => {},
  },
  { passive: true },
);

// createEventListenerMap can be used to listen to custom events
// fill both type generics for the best type support
createEventListenerMap<{
  myEvent: MyEvent;
  custom: Event;
  other: Event;
}>(target, {
  myEvent: e => {},
  custom: e => {},
});

WindowEventListener

Listen to the window DOM Events, using a component.

You can use it with any Solid's Control-Flow components, e.g. <Show/> or <Switch/>.

The event handler prop is reactive, so you can use it with signals.

How to use it

import { WindowEventListener } from "@solid-primitives/event-listener";

<WindowEventListener onMouseMove={e => console.log(e.x, e.y)} />;

DocumentEventListener

The same as WindowEventListener, but listens to document events.

How to use it

import { DocumentEventListener } from "@solid-primitives/event-listener";

<DocumentEventListener onMouseMove={e => console.log(e.x, e.y)} />;

Callback Wrappers

preventDefault

Wraps event handler with e.preventDefault() call.

import { preventDefault, makeEventListener } from "@solid-primitives/event-listener";

const handleClick = e => {
  concole.log("Click!", e);
};

makeEventListener(window, "click", preventDefault(handleClick), true);
// or in jsx:
<div onClick={preventDefault(handleClick)} />;

stopPropagation

Wraps event handler with e.stopPropagation() call.

import { stopPropagation, makeEventListener } from "@solid-primitives/event-listener";

const handleClick = e => {
  concole.log("Click!", e);
};

makeEventListener(window, "click", stopPropagation(handleClick), true);
// or in jsx:
<div onClick={stopPropagation(handleClick)} />;

stopImmediatePropagation

Wraps event handler with e.stopImmediatePropagation() call.

import { stopImmediatePropagation, makeEventListener } from "@solid-primitives/event-listener";

const handleClick = e => {
  concole.log("Click!", e);
};

makeEventListener(window, "click", stopImmediatePropagation(handleClick), true);
// or in jsx:
<div onClick={stopImmediatePropagation(handleClick)} />;

Changelog

See CHANGELOG.md

Similar packages

Other packages similar to @solid-primitives/event-listener

react-use

react-use is a collection of essential React Hooks, including hooks for managing event listeners. It provides similar functionality for React applications, allowing developers to easily manage event listeners in a declarative way. Unlike @solid-primitives/event-listener, which is specific to SolidJS, react-use is tailored for React.

use-gesture

use-gesture is a library for handling gestures in React applications. It provides hooks for managing complex gesture interactions, such as dragging and pinching. While it offers more advanced gesture handling compared to @solid-primitives/event-listener, it is specific to React and focuses on gesture events rather than general event listeners.

add-event-listener

add-event-listener is a simple utility for adding and removing event listeners in JavaScript. It is a more general-purpose library compared to @solid-primitives/event-listener, which is specifically designed for use with SolidJS and provides reactive management of event listeners.