DOCSEARCHbyAlgolia
Submit Docs

DragDropTouch Documentation

repository·master·Indexed 19 days ago

https://github.com/drag-drop-touch-js/dragdroptouch

A polyfill that enables standard HTML5 drag-and-drop functionality on mobile and touch-enabled devices by translating touch events into drag and drop events. Available as the @dragdroptouch/drag-drop-touch package, it supports installation via npm, yarn, pnpm, CDN, or as a script file. It provides configurable options for drag thresholds, press-hold modes, and scroll behavior to ensure compatibility across touch devices.

Tokens
1.1K
Snippets
4
Records
6
Agent score
18%

What's inside DragDropTouch

  1. How DragDropTouch polyfills touch events

    master

    The polyfill translates touch events into standard HTML5 drag and drop events using the following lifecycle:

    1. touchstart: Checks if the target or its ancestor has the draggable attribute. If so, it saves the drag source and prevents default handling.
    2. touchmove: Monitors movement. Once the movement exceeds a threshold, it raises dragstart and continues to fire dragenter and dragleave.
    3. touchend: Raises dragend and drop events.

    To maintain compatibility with standard mouse interactions, the polyfill also raises mousemove, mousedown, mouseup, and click events when a user touches a draggable element without initiating a drag, as well as dblclick and contextmenu events.

  2. Install DragDropTouch as a script file

    master

    You can add the polyfill directly to your HTML page. To enable it immediately without writing any additional JavaScript, append the ?autoload query argument to the script source.

    Note: You must use type="module" in your script tag to avoid syntax errors related to import.meta.

    <!-- Automatically enables the polyfill on the entire page -->
<script src="drag-drop-touch.esm.min.js?autoload" type="module"></script>

  3. Install DragDropTouch via package manager

    master

    You can install the polyfill using npm, yarn, or pnpm. The package is available in the npm registry as @dragdroptouch/drag-drop-touch.

    npm install -s @dragdroptouch/drag-drop-touch
yarn install @dragdroptouch/drag-drop-touch
pnpm add @dragdroptouch/drag-drop-touch

  5. Configure DragDropTouch options

    master

    The enableDragDropTouch function (or the DragDropTouch.enable method if not using autoload) accepts an optional options object to customize polyfill behavior.

    Key configuration options include:

    • allowDragScroll (boolean, default: true): Whether to allow scrolling when a drag reaches screen edges.
    • contextMenuDelayMS (number, default: 900): Milliseconds to wait before triggering a context menu on long press.
    • dragImageOpacity (number [0, 1], default: 0.5): Transparency of the drag placeholder.
    • dragScrollPercentage (number, default: 10): Size of the edge 'hot region' for scrolling.
    • dragScrollSpeed (number, default: 10): Pixels to scroll when in a hot region.
    • dragThresholdPixels (number, default: 5): Pixels a touch must move to switch from click to drag mode.
    • isPressHoldMode (boolean, default: false): If true, requires a long-press before enabling drag events.
    • forceListen (boolean, default: true): Enables polyfill regardless of whether the browser reports touch support.
    • pressHoldDelayMS (number, default: 400): Milliseconds to wait before considering a press a 'long press'.
    • pressHoldMargin (number, default: 25): Allowed drift in pixels during a long press start.
    • pressHoldThresholdPixels (number, default: 0): Drift in pixels that determines if a long press starts or becomes a touch-drag.

  6. Use DragDropTouch as an ES module

    master

    If you are using a module bundler or modern browser, you can import enableDragDropTouch directly into your JavaScript files. You can use it to polyfill the entire page, specific elements, or apply custom configuration options.

    import { enableDragDropTouch } from "./drag-drop-touch.esm.min.js";

// Set up the default full page polyfill:
enableDragDropTouch();

// Or, explicitly polyfill only certain elements
enableDragDropTouch(dragRootElement, dropRootElement);

// Or, explicitly polyfill only certain elements with non-default behaviour
const options = {
  // ...
};
enableDragDropTouch(dragRootElement, dropRootElement, options);