DragDropTouch

Polyfill that enables HTML5 drag drop support on mobile (touch) devices.

The HTML5 specification includes support for drag and drop operations.
Unfortunately, this specification is based on mouse events, rather than
pointer events, and so most mobile browsers do not implement it. As such,
applications that rely on HTML5 drag and drop have reduced functionality
when running on mobile devices.

The DragDropTouch class is a polyfill that translates touch events into
standard HTML5 drag drop events. If you add the polyfill to your pages,
drag and drop operations should work on mobile devices just like they
do on the desktop.

Demo

- Click here to play with the demo

This demo should work on desktop as well as on mobile devices, including
iPads and Android tablets. To test this on a desktop, turn on "responsive
design mode", which is both a button in the browser developer tools, as
well as the hot-key ctrl-shift-M on Windows and Linux, or
cmd-shift-M on Mac.

How to "install"

$3

This package lives in the npm registry as @dragdroptouch/drag-drop-touch
and can be installed with any package manager that can pull from the
npm registery:

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

$3

Add the
drag-drop-touch.esm.js
or
drag-drop-touch.esm.min.js
polyfill script to your page to enable drag and drop on devices with touch input:

`html

`

Note the ?autoload query argument on the src URL: this loads the polyfill
and immediately enables it so that you do not need to write any code yourself.
If omitted, the library will instead set up a window.DragDropTouch object
with a single function, DragDropTouch.enable(dragRoot, dropRoot, options).
All three arguments are optional. If left off, DragDropTouch.enable() simply
polyfills the entire page. If you only want the polyfill to apply to specific
elements though, you can call the enable function once for each set of
elements that need polyfilling.

Also note the type="module", which is required. If left off, you'll probably
get a browser error similar to:

`
Uncaught SyntaxError: import.meta may only appear in a module
`

$3

You can also load the library using a CDN solution such as jsDelivr:

`html
src="https://cdn.jsdelivr.net/npm/@dragdroptouch/drag-drop-touch@latest/dist/drag-drop-touch.esm.min.js"
type="module"
>
`

This is a JS ES module

As an ES module, you can also use this polyfill as an import in any other script:

`js
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 even explicitly polyfill only certain elements with non-default behaviour
const options = {
// ...
};
enableDragDropTouch(dragRootElement, dropRootElement, options);
`

Polyfill behaviour

The DragDropTouch polyfill attaches listeners to the document's touch events:

- On touchstart, it checks whether the target element has the draggable
attribute or is contained in an element that does. If that is the case, it
saves a reference to the "drag source" element and prevents the default
handling of the event.
- On touchmove, it checks whether the touch has moved a certain threshold
distance from the origin. If that is the case, it raises the dragstart
event and continues monitoring moves to fire dragenter and dragleave.
- On touchend, it raises the dragend and drop events.

To avoid interfering with the automatic browser translation of some touch events
into mouse events, the polyfill performs a few additional tasks:

- Raise the mousemove, mousedown, mouseup, and click events when
the user touches a draggable element but doesn't start dragging,
- Raise the dblclick event when there's a new touchstart right after a click,
and
- Raise the contextmenu event when the touch lasts a while but the user doesn't
start dragging the element.

Overriding polyfill behaviour

The following options can be passed into the enabling function to change how the
polyfill works:

- allowDragScroll is a flag that determines whether to allow scrolling when
a drag reaches the edges of the screen. This can be either true or false,
and is true by default.
- contextMenuDelayMS is the number of milliseconds we'll wait before the
polyfill triggers a context menu event on long press. This value is 900 by
default.
- dragImageOpacity determines how see-through the "drag placeholder", that's
attached to the cursor while dragging, should be. This value is a number in
the interval [0, 1], where 0 means fully transparent, and 1 means fully opaque.
This value is 0.5 by default.
- dragScrollPercentage is the size of the "hot region" at the edge of the
screen as a percentage value on which scrolling will be allowed, if the
allowDragScroll flag is true (which is its default value). This value is
10 by default.
- dragScrollSpeed is the number of pixels to scroll if a drag event occurs
within a scrolling hot region. This value is 10 by default.
- dragThresholdPixels is the number of pixels that a touchmove needs to
actually move before the polyfill switches to drag mode rather than click mode.
This value is 5 by default
- isPressHoldMode is a flag that tells the polyfill whether a a long-press
is required before polyfilling drag events. This value can be either true or
false, and is false by default.
- forceListen is a flag that determines whether the polyfill should be
enabled irrespective of whether the browser indicates that it's running on
a touch-enabled device or not. This value is true by default.
- pressHoldDelayMS: is the number of milliseconds the polyfill will wait
before it considers an active press to be a "long press". This value is 400
by default.
- pressHoldMargin is the number of pixels we allow a touch event to drift
over the course of a long press start. This value is 25 by default.
- pressHoldThresholdPixels is the drift in pixels that determines whether
a long press actually starts a long press, or starts a touch-drag instead.
This value is 0 by default.

Thanks

- Thanks to Eric Bidelman for the great tutorial on HTML5 drag and drop:
Native HTML5 Drag and Drop.
- Thanks also to Chris Wilson and Paul Kinlan for their article on mouse and touch events:
Touch And Mouse.
- Thanks to Tim Ruffles for his iOS shim code which was inspiring:
iOS DragDrop Shim.

License

MIT License

For developers

If you wish to work on this library, fork and clone the repository, then run
npm install to install all the dependency, followed by a one-time
npm run dev:setup, which will install the necessary components for running
the integration tests.

$3

This repository uses the standard npm test command to run build and
integration tests. Build testing consists of linting the source code using tsc,
auto-formatting it using prettier, and compiling it into three bundles (debug, normal, and minified) using esbuild. Integration tests are found in the
tests/touch.spec.js file, using Playwright as test runner.

Additionally, npm run test:debug will run the tests with DEBUG statements preserved, useful for when tests fail to pass and you're trying to find out what's actually happening.

$3

To manually test in the browser, you can run npm start and then open the
URL that is printed to the console once the initial build tasks have finished.
This runs a local server that lets you run the demo page, but with the
drag-drop-touch.esm.min.js replaced by a drag-drop-touch.debug.esm.js
instead, which preserves all debug statements used in the TypeScript source.

To add your own debug statements, use the DEBUG:` label followed by either
a normal statement, or multiple statements wrapped in a new block.