svelte-gestures

Most gesture recognizers in svelte-gestures trigger a main event and three lifecycle events based on the pointer state: [gesture][up], [gesture][down], and [gesture][move].

For example, the pan action triggers pan, panup, pandown, and panmove.

Each event dispatches event.detail containing a common set of properties. While specific properties vary by gesture, they generally include:

• event: The native PointerEvent.
• pointersCount: The number of active pointers.
• target: The HTMLElement where the gesture started.
• x, y: Coordinates within the gesture element.
• pointerType: 'touch' | 'mouse' | 'pen'.

<script lang="ts">
  import { pan, type PanCustomEvent, type GestureCustomEvent } from 'svelte-gestures';
  let x: number;
  let y: number;
  let target: EventTarget;

  function handler(event: PanCustomEvent) { 
    x = event.detail.x;
    y = event.detail.y;
    target = event.detail.target;
  }

  function panDown(gestureEvent: GestureCustomEvent) { 
    const { event, pointersCount, target, x, y } = gestureEvent.detail;
  }

  function panMove(gestureEvent: GestureCustomEvent) { 
    console.log(gestureEvent.detail);
  }
</script>

<div
  use:pan
  on:pan={handler}
  on:pandown={panDown}
  on:panmove={panMove}
  style="width:500px;height:500px;border:1px solid black;"
></div>

In version 5.x, recognizers are implemented as Svelte Attachments. They are used with the use directive (e.g., usePan) and act as custom event emitters.

Each gesture attachment typically accepts four arguments:

1. Main Handler: A function triggered when the primary gesture is recognized.
2. Options Function: A function that returns an options object. Wrapping this in a function allows you to change gesture parameters dynamically during the component lifecycle.
3. Extra Event Handlers: An object containing handlers for sub-events (e.g., onpanup, onpandown, onpanmove).
4. isRaw (boolean): If true, the attachment returns the raw gesture function and event handlers instead of a standard Svelte attachment object. This is useful for using the @attach syntax on elements like <svelte:body> or for programmatic addEventListener usage.

<script lang="ts">
	import { useSwipe, type SwipeCustomEvent } from 'svelte-gestures';
	
	function handler(event: SwipeCustomEvent) {
		console.log(event.detail.direction);
	}
</script>

<section
	{...useSwipe(handler, () => ({ timeframe: 300, minSwipeDistance: 50, touchAction: 'none' }))}>
		<div>Swipe me</div>
</section>

The composedGesture action is used to compose multiple gestures together or switch between gestures dynamically during a single interaction. It does not listen to gestures itself but acts as a controller.

To use it, pass a function with the signature: (register: RegisterGestureType) => (activeEvents: PointerEvent[], event: PointerEvent) => boolean

Inside this function, you use the register callback to add gestures. register returns an object containing onDown, onMove, and onUp callbacks. While onDown and onUp are managed by composedGesture, you must manually trigger the onMove callbacks within the returned function to implement custom logic (e.g., switching from scrolling to panning based on a press).

// Example signature for the composedGesture function
const myComposedGesture: GestureCallback = (register: RegisterGestureType) => {
  const gestureA = register(gestureA_Fn, optionsA);
  const gestureB = register(gestureB_Fn, optionsB);

  return (activeEvents: PointerEvent[], event: PointerEvent) => {
    // Logic to decide which gesture's move handler to run
    if (condition) {
      gestureA.onMove(activeEvents, event);
    } else {
      gestureB.onMove(activeEvents, event);
    }
  };
};

A composedGesture does not listen to gestures itself; instead, it acts as a container to compose multiple gestures or switch between them during a single interaction. This is useful for complex logic, such as distinguishing between a 'scroll' and a 'pan' based on whether a 'press' was initially triggered.

To use it, pass a function to useComposedGesture with the signature: (register: RegisterFnType) => (activeEvents: PointerEvent[], event: PointerEvent) => boolean.

Inside the function, you use register(gesture, options) to add gestures. Each registration returns an object with onDown, onMove, and onUp. You must return a callback from your function that explicitly triggers the onMove methods of the registered gestures.

useComposedGesture((register) => {
  const pan = register(pan, { /* options */ });
  const press = register(press, { /* options */ });

  return (activeEvents, event) => {
    // Logic to decide which onMove to call
    if (press.isTriggered) {
      return pan.onMove(activeEvents, event);
    }
    return false;
  };
});

The swipe action (triggered via on:swipe) fires if a pointer moves a minimum distance within a specific timeframe in a single direction.

Options:

• timeframe (default: 300ms): The maximum time allowed for the swipe.
• minSwipeDistance (default: 60px): The minimum distance required to trigger the swipe.
• touchAction (default: 'none'): CSS touch-action style.
• composed: Only applicable when used inside a composedGesture.

Event Detail Properties:

• direction: 'top' | 'right' | 'bottom' | 'left'.
• target: The HTMLElement recorded when the swipe starts.
• pointerType: 'touch' | 'mouse' | 'pen'.

<script lang="ts">
import { swipe, type SwipeCustomEvent } from 'svelte-gestures';
let direction, target, pointerType;

function handler(event: SwipeCustomEvent) {
  direction = event.detail.direction;
  target = event.detail.target;
  pointerType = event.detail.pointerType;
}
</script>

<div 
  use:swipe={{ timeframe: 300, minSwipeDistance: 60 }} 
  on:swipe={handler} 
  style="width:500px;height:500px;border:1px solid black;"
>
  direction: {direction}
</div>