README

Draggable

Usage

• NPM:

import {Draggable} from '@shopify/draggable';
// Or
import Draggable from '@shopify/draggable/build/esm/Draggable/Draggable';

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
});

• Browser (as a module):

<script type="module">
  import Draggable from 'https://cdn.jsdelivr.net/npm/@shopify/draggable/build/esm/Draggable/Draggable.mjs';

  const draggable = new Draggable(document.querySelectorAll('ul'), {
    draggable: 'li',
  });
</script>

• Browser (Standalone):

<script src="https://cdn.jsdelivr.net/npm/@shopify/draggable/build/umd/index.min.js"></script>
<script>
  const draggable = new Draggable.Draggable(document.querySelectorAll('ul'), {
    draggable: 'li',
  });
</script>

API

new Draggable(containers: HTMLElement[]|NodeList|HTMLElement, options: Object): Draggable
To create a draggable instance you need to specify the container(s) that hold draggable items, e.g. document.body would work too. The second argument is an options object, which is described below.

draggable.destroy(): void
Detaches all sensors and listeners, and cleans up after itself.

draggable.on(eventName: String, listener: Function): Draggable
Draggable is an event emitter, so you can register callbacks for events. Draggable also supports method chaining.

draggable.off(eventName: String, listener: Function): Draggable
You can unregister listeners by using .off(), make sure to provide the same callback.

draggable.trigger(event: AbstractEvent): void
You can trigger events through draggable. This is used to fire events internally or by extensions of Draggable.

draggable.addPlugin(plugins: ...typeof Plugin): Draggable
Adds plugins to this draggable instance.

draggable.removePlugin(plugins: ...typeof Plugin): Draggable
Removes plugins that are already attached to this draggable instance.

draggable.addSensor(sensors: ...typeof Sensor): Draggable
Adds sensors to this draggable instance.

draggable.removeSensor(sensors: ...typeof Sensor): Draggable
Removes sensors that are already attached to this draggable instance.

draggable.addContainer(containers: ...HTMLElement): Draggable
Adds containers to this draggable instance.

draggable.removeContainer(containers: ...HTMLElement): Draggable
Removes containers from this draggable instance.

draggable.getClassNameFor(name: String): String
Returns class name for class identifier, check the classes table below for identifiers.

draggable.getClassNamesFor(name: String): String[]
Returns array of class name for class identifier, useful when working with atomic css, check the classes table below for identifiers.

draggable.isDragging(): Boolean
Returns true or false, depending on this draggables dragging state.

draggable.getDraggableElementsForContainer(container: HTMLElement): HTMLElement[]
Returns draggable elements for given container, excluding potential mirror or original so urce. draggable.cancel(): void
Cancel current dragging state immediately NOTE: Can't revert elements that were changed to the beginning state (e.g sorted elements)

Options

draggable {String}
A css selector for draggable elements within the containers specified. By default it will look for an element with .draggable-source class. Default: .draggable-source

handle {String}
Specify a css selector for a handle element if you don't want to allow drag action on the entire element. Default: null

delay {Number|Object}
If you want to delay a drag start you can specify delay in milliseconds. This can be useful for draggable elements within scrollable containers. To allow touch scrolling, we set 100ms delay for TouchSensor by default. Default:

{
  mouse: 0,
  drag: 0,
  touch: 100,
}

You can set the same delay for all sensors by setting a number, or set an object to set the delay for each sensor separately.

distance {Number}
The distance you want the pointer to have moved before drag starts. This can be useful for clickable draggable elements, such as links. Default: 0

plugins {Plugin[]}
Plugins add behaviour to Draggable by hooking into its life cycle, e.g. one of the default plugins controls the mirror movement. Default: []

sensors {Sensor[]}
Sensors dictate how drag operations get triggered, by listening to native browser events. By default draggable includes the MouseSensor & TouchSensor. Default: []

classes {{String: String|String[]}}
Draggable adds classes to elements to indicate state. These classes can be used to add styling on elements in certain states. Accept String or Array of strings.

NOTE: When specifying multiple classes to an indicate state, the first class MUST be unique for that state to avoid duplicate classes for other states. IE doesn't support add or remove multiple classes. If you want to use multiple classes in IE, you need to add a classList polyfill to your project first.

exclude {plugins: Plugin[], sensors: Sensor[]}
Allow excluding default plugins and default sensors. Use with caution as it may create strange behavior.

Events

Classes

Examples

This sample code will make list items draggable:

import {Draggable} from '@shopify/draggable';

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
});

draggable.on('drag:start', () => console.log('drag:start'));
draggable.on('drag:move', () => console.log('drag:move'));
draggable.on('drag:stop', () => console.log('drag:stop'));

Create draggable which excluded some default plugins and sensor:

import {Draggable} from '@shopify/draggable';

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
  exclude: {
    plugins: [Draggable.Plugins.Focusable],
    sensors: [Draggable.Sensors.TouchSensor],
  },
});

Create draggable with specific classes:

import {Draggable} from '@shopify/draggable';

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
  classes: {
    'draggable:over': ['draggable--over', 'bg-red-200', 'bg-opacity-25'],
  },
});

Cancel dragging on ESC key up:

import {Draggable} from '@shopify/draggable';

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
  classes: {
    'draggable:over': ['draggable--over', 'bg-red-200', 'bg-opacity-25'],
  },
});