multiPointers

Multi-touch pointer stream that tracks multiple simultaneous pointers. Emits a snapshot of all active pointers whenever any pointer changes state.

Terminal window
npm install --save cereb

Basic Usage

import { multiPointers } from "cereb";


multiPointers(element, { maxPointers: 2 }).on((signal) => {
  const { phase, pointers, count } = signal.value;


  if (count === 2) {
    const [p1, p2] = pointers;
    const [x1, y1] = p1.cursor;
    const [x2, y2] = p2.cursor;
    console.log(`Two fingers at (${x1}, ${y1}) and (${x2}, ${y2})`);
  }
});

Signature

function multiPointers(target: EventTarget, options?: MultiPointersOptions): Stream<MultiPointersSignal>

Options

OptionTypeDefaultDescription
maxPointersnumber2Maximum pointers to track simultaneously

Signal Value

The signal.value contains:

PropertyTypeDescription
phase"idle" | "active" | "ended"Session-level phase
pointersreadonly PointerInfo[]Array of all active pointers
countnumberNumber of active pointers

PointerInfo

Each pointer in the pointers array contains:

PropertyTypeDescription
idstringUnique pointer identifier
phase"start" | "move" | "end" | "cancel"Individual pointer phase
cursor[number, number]Current position [x, y] (client)
pageCursor[number, number]Current position [pageX, pageY] (page)
pointerType"mouse" | "touch" | "pen" | "unknown"Input device type
button"none" | "primary" | "secondary" | ...Mouse button pressed
pressurenumberPressure value (0.0-1.0)

Phase Lifecycle

first pointer down → "active" → (pointers change) → last pointer up → "ended" → "idle"
  • idle: No active pointers
  • active: One or more pointers are active
  • ended: All pointers have ended (transition state)

With Pinch Gesture

multiPointers is the foundation for pinch gestures:

import { multiPointers } from "cereb";
import { multiPointersSession } from "cereb/operators";
import { pinchRecognizer } from "cereb";


multiPointers(element, { maxPointers: 2 })
  .pipe(
    multiPointersSession(2),  // Wait for 2 pointers
    pinchRecognizer()
  )
  .on((signal) => {
    const { ratio, center } = signal.value;
    const [cx, cy] = center;
    // Handle pinch...
  });

Advanced: multiPointersFromPointer

Use as an operator with custom event sources:

import { pointerEvents } from "cereb";
import { multiPointersFromPointer } from "cereb";


pointerEvents(element)
  .pipe(multiPointersFromPointer({ maxPointers: 3 }))
  .on((signal) => { /* ... */ });