Mouse

A collection of primitives that capture current mouse cursor position, and help to deal with common related usecases.

Stage	Category	Version	Last Updated	Demo
3	Inputs	4.0.0-next.3 (next)	Aug 13, 2026	Demo →

npm i @solid-primitives/mouse@next

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.

`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);

Changelog

See CHANGELOG.md