Draggable →

Draggable Helpers

A collection of official helper functions for creating custom draggable logic.

createTouchDelayPredicate

DANGER

This helper is experimental, unfortunately. Preventing native scroll on touch devices after touchstart event is finicky. It doesn't always work reliably. And it gets especially tricky within iframes. Consider this helper a best effort, use with caution and test thoroughly.

A custom start predicate for starting drag after a long press on touch devices. Assumes you are using PointerSensor for the Draggable instance.

For mouse and pen events the predicate is resolved immediately. For touch events the predicate has special logic to start the drag after a long press, whose duration can be adjusted with touchDelay parameter. If scrolling is detected before the long press finishes, the drag will not start.

Examples

import { Draggable } from 'dragdoll/draggable';
import { PointerSensor } from 'dragdoll/sensors/pointer';
import { KeyboardSensor } from 'dragdoll/sensors/keyboard';
import { createTouchDelayPredicate } from 'dragdoll/draggable/helpers/create-touch-delay-predicate';

const element = document.querySelector('.draggable') as HTMLElement;
const pointerSensor = new PointerSensor(element);
const keyboardSensor = new KeyboardSensor(element);
const draggable = new Draggable([pointerSensor, keyboardSensor], {
  elements: () => [element],
  startPredicate: createTouchDelayPredicate({
    // The amount of time in milliseconds to wait before trying to start
    // dragging after the user has touched the pointer sensor element.
    touchDelay: 200,
    fallback: (data) => {
      // Here you can decide what to do with the other sensors' events.
      // For example, if you are using the keyboard sensor and pointer sensor
      // together and user uses both the keyboard and the pointer at the same
      // time, you can decide the logic for keyboard events here (when should
      // the dragging start).
      console.log(data);
      return true;
    },
  }),
});

Syntax

function createTouchDelayPredicate<
  S extends (Sensor | PointerSensor)[] = (
    | Sensor<SensorEvents>
    | PointerSensor<PointerSensorEvents>
  )[],
>(options?: {
  touchDelay?: number;
  fallback?: Draggable<S>['settings']['startPredicate'];
}): (data: {
  draggable: Draggable<S, {}>;
  sensor: S[number];
  event: S[number]['_events_type']['start'] | S[number]['_events_type']['move'];
}) => boolean | undefined;

Parameters

1. options
   • An optional configuration object with the following properties:
     • touchDelay
       • The amount of time in milliseconds to wait before trying to start dragging after the user has touched the pointer sensor element (applies for touch events only). The point of this delay is to allow users to scroll normally if they don't intend to drag and start dragging only after long press, which is a common pattern in mobile applications.
       • Default is 250.
     • fallback
       • Fallback start predicate function that will be called for other sensors' events (e.g. keyboard sensor) if there are any.
       • Default is () => true.

Returns

A start predicate function that can be provided to the startPredicate option of the Draggable constructor.