@solid-primitives/pointer

@solid-primitives/pointer

A collection of primitives, giving you a nicer API to handle pointer events in a reactive context.

• createPointerListeners - Setups event listeners for pointer events, that will get automatically removed on cleanup,
• createPerPointerListeners - Setup pointer event listeners, while following the pointers individually, from when they appear, until they're gone,
• createPointerPosition - Returns a signal with autoupdating Pointer position,
• createPointerList - Provides a signal of current pointers on screen
• pointerHover - A directive for checking if the element is being hovered by at least one pointer.

Installation

npm install @solid-primitives/pointer
# or
yarn add @solid-primitives/pointer

createPointerListeners

Setups event listeners for pointer events, that will get automatically removed on cleanup

Import

import { createPointerListeners } from "@solid-primitives/pointer";

How to use it

Primitive takes one config argument, of options:

• target - specify the target to attach the listeners to. Will default to document.body
• pointerTypes - specify array of pointer types you want to listen to. By default listens to ["mouse", "touch", "pen"]
• passive - Add passive option to event listeners. Defaults to true.
• your event handlers: e.g. onenter, onLeave, onMove, ...

createPointerListeners({
  // pass a function if the element is yet to mount
  target: () => el,
  pointerTypes: ["touch"],
  // both lowerace or capitalized kays work
  onEnter: e => console.log("enter", e.x, e.y),
  onmove: e => console.log({ x: e.x, y: e.y }),
  onup: e => console.log("pointer up", e.x, e.y),
  onLostCapture: e => console.log("lost"),
});

createPerPointerListeners

Setup pointer event listeners, while following the pointers individually, from when they appear, until they're gone.

Import

import { createPerPointerListeners } from "@solid-primitives/pointer";

How to use it

Primitive takes one config argument, of options:

• target - specify the target to attach the listeners to. Will default to document.body
• pointerTypes - specify array of pointer types you want to listen to. By default listens to ["mouse", "touch", "pen"]
• passive - Add passive option to event listeners. Defaults to true.
• onDown - Start following a pointer from when it's down.
• onEnter - Start following a pointer from when it enters the screen.

onDown

onDown starts when pointer is down, and ends when that pointer is up. You can create move and up listeners when the onStart runs, to listen to later events of that pointer.

createPerPointerListeners({
  target: el,
  pointerTypes: ['touch', 'pen'],
  onDown({ x, y, pointerId }, onMove, onUp) {
    console.log(x, y, pointerId);
    onMove(e => {...});
    onUp(e => {...});
  }
})

onEnter

onEnter fires when pointer appears on the screen, and ends then that pointer leaves the screen. You can listen to "down" | "move" | "up" | "leave" | "cancel" events of that pointer.

createPerPointerListeners({
  onEnter({ x, y, pointerId }, { onMove, onLeave, onDown }) {
    console.log("New pointer:", pointerId);
    onDown(e => {...});
    onMove(e => {...});
    onLeave(e => {...});
  }
});

DEMO

https://codesandbox.io/s/solid-primitives-pointer-demo-zryr5h?file=/app.tsx

createPointerPosition

Returns a signal with autoupdating Pointer position.

Import

import { createPointerPosition } from "@solid-primitives/pointer";

How to use it

Primitive takes one config argument, of options:

• target - specify the target to attach the listeners to. Will default to document.body
• pointerTypes - specify array of pointer types you want to listen to. By default listens to ["mouse", "touch", "pen"]
• value - set the initial value of the returned signal (before the first event)

const position = createPointerPosition({
  target: document.querySelector("my-el"),
  pointerTypes: ["touch"],
});

createEffect(() => {
  console.log("position", position().x, position().y);
  console.log("hovering", position().isActive);
});

As a directive

import { pointerPosition } from "@solid-primitives/pointer";
// place this in code to avoid being tree-shaken
pointerPosition;

const [pos, setPos] = createSignal({ x: 0, y: 0 });
const [hovering, setHovering] = createSignal(false);

<div
  use:pointerPosition={e => {
    setPos({ x: e.x, y: e.y });
    setHovering(e.isActive);
  }}
/>;

createPointerList

Provides a signal of current pointers on screen.

Import

import { createPointerList } from "@solid-primitives/pointer";

How to use it

Primitive takes one config argument, of options:

• target - specify the target to attach the listeners to. Will default to document.body
• pointerTypes - specify array of pointer types you want to listen to. By default listens to ["mouse", "touch", "pen"]

Returns a list of pointers on the screen:

Accessor<Accessor<PointerListItem>[]>;

Basic example:

const points = createPointerList();

// notice that points is an signal returning an array of signals
<For each={points()}>{poz => <div>{poz()}</div>}</For>;

pointerHover

A directive for checking if the element is being hovered by at least one pointer.

How to use it

import { pointerHover } from "@solid-primitives/pointer";
// place this in code to avoid being tree-shaken
pointerHover;

const [hovering, setHovering] = createSignal(false);

<div use:pointerHover={setHovering} />;

Changelog

See CHANGELOG.md