@solid-primitives/mouse

A collection of primitives, capturing current mouse cursor position, and helping to deal with common usecases:

Reactive primitives:

• createMousePosition - Listens to the mouse events, providing a reactive up-to-date position of the cursor on the page.
• createPositionToElement - Provides an auto-updating position relative to a provided element.

Non-reactive primitives:

• makeMousePositionListener - Attaches event listeners to provided target, listening for changes to the mouse/touch position.
• makeMouseInsideListener - Attaches event listeners to provided target, listening for mouse/touch entering/leaving the element.

Calculations:

• getPositionToElement - Turn position relative to the page, into position relative to an element.
• getPositionInElement - Turn position relative to the page, into position relative to an element. Clamped to the element bounds.
• getPositionToScreen - Turn position relative to the page, into position relative to the screen.

Installation

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

createMousePosition

Attaches event listeners to provided target, providing a reactive up-to-date position of the cursor on the page.

Usage

import { createMousePosition } from "@solid-primitives/mouse";

const pos = createMousePosition(window);
createEffect(() => {
  console.log(pos.x, pos.y);
});

// target can be a reactive signal
const [el, setEl] = createSignal(ref);
const pos = createMousePosition(el);

// if using a jsx ref, pass it as a function, or wrap primitive inside onMount
let ref;
const pos = createMousePosition(() => ref);
<div ref={ref}></div>;

By default createMousePosition is listening to touch events as well. You can disable that behavior with touch and followTouch options.

// disables following touch position – only registers touch start
const pos = createMousePosition(window, { followTouch: false });

// disables listening to any touch events
const pos = createMousePosition(window, { touch: false });

useMousePosition

This primitive provides a singleton root variant that will listen to window mouse position, and reuse event listeners and signals across dependents.

const pos = useMousePosition();
createEffect(() => {
  console.log(pos.x, pos.y);
});

Definition

function createMousePosition(
  target?: MaybeAccessor<SVGSVGElement | HTMLElement | Window | Document>,
  options?: MousePositionOptions,
): MousePositionInside;

createPositionToElement

Provides an autoupdating position relative to an element based on provided page position.

Usage

import { createPositionToElement, useMousePosition } from "@solid-primitives/mouse";

const pos = useMousePosition();
const relative = createPositionToElement(ref, () => pos);

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

// target can be a reactive signal
const [el, setEl] = createSignal(ref);
const relative = createPositionToElement(el, () => pos);

// if using a jsx ref, pass it as a function, or wrap primitive inside onMount
let ref;
const relative = createPositionToElement(() => ref);
<div ref={ref}></div>;

Definition

function createPositionToElement(
  element: Element | Accessor<Element | undefined>,
  pos: Accessor<Position>,
  options?: PositionToElementOptions,
): PositionRelativeToElement;

Non-reactive primitives:

makeMousePositionListener

Added id @2.0.0

Attaches event listeners to provided target, listening for changes to the mouse/touch position.

const clear = makeMousePositionListener(el, pos => console.log(pos), { touch: false });
// remove listeners manually (will happen on cleanup)
clear();

makeMouseInsideListener

Added id @2.0.0

Attaches event listeners to provided target, listening for mouse/touch entering/leaving the element.

const clear = makeMouseInsideListener(el, inside => console.log(inside), { touch: false });
// remove listeners manually (will happen on cleanup)
clear();

Calculations

getPositionToElement

Turn position relative to the page, into position relative to an element.

const pos = getPositionToElement(pageX, pageY, element);

getPositionInElement

Turn position relative to the page, into position relative to an element. Clamped to the element bounds.

const pos = getPositionInElement(pageX, pageY, element);

getPositionToScreen

Turn position relative to the page, into position relative to the screen.

const pos = getPositionToScreen(pageX, pageY);

Demo

https://codesandbox.io/s/solid-primitives-mouse-p10s5?file=/index.tsx

Changelog

See CHANGELOG.md