The JavaScript Drag & Drop library your grandparents warned you about.

Warning: Draggable is still in beta version

Get complete control over drag and drop behavior with Draggable! Draggable abstracts native browser events into a complex API to create a custom drag and drop experience. Draggable comes with additional modules: Sortable, Droppable, Swappable. Draggable itself does not perform any sorting behavior while dragging, but does the heavy lifting, e.g. creates mirror, emits events, manages sensor events, makes elements draggable.

The additional modules are built on top of Draggable and therefore provide a similar API interface, read the documentation below.

Features

• Works with native drag, mouse, touch and force touch events
• Can extend dragging behavior by hooking into draggables event life cycle
• Can extend drag detection by adding sensors to draggable
• The library is modular, so you can require what you need only

Table of Contents

• Install
• Draggable
  • API
  • Options
  • Events
  • Classes
  • Example
• Sortable
  • API
  • Options
  • Events
  • Classes
  • Example
• Droppable
  • API
  • Options
  • Events
  • Classes
  • Example
• Swappable
  • API
  • Options
  • Events
  • Classes
  • Example
• Plugins
  • Collidable
  • Snappable
• Contributing

Install

You can install the library via npm.

npm install @shopify/draggable --save

or via yarn:

yarn add @shopify/draggable

Draggable

API

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

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(eventName: String, event: AbstractEvent): Draggable You can trigger events through draggable. This is used to fire events internally or by extensions of Draggable.

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

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} If you want to delay a drag start you can specify delay in milliseconds. This can be useful for draggable elements within scrollable containers. Default: 0

native {Boolean} If enabled Draggable will use the browsers native drag events to detect drag behavior. By default it will use mouse events to detect drag behavior. You can only customize the mirror element when using mouse events, otherwise mirror will be null in events. Default: false

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

classes {Object} Draggable adds classes to elements to indicate state. These classes can be used to add styling on elements in certain states.

Events

Classes

Example

This sample code will make list items draggable:

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

new Draggable(document.querySelectorAll('ul'))
  .on('drag:start', () => console.log('drag:start'))
  .on('drag:move',  () => console.log('drag:move'))
  .on('drag:stop',  () => console.log('drag:stop'));

Sortable

Sortable allows you to reorder elements. It maintains the order internally and fires three events on top of the draggable events: sortable:start, sortable:sorted and sortable:stop.

API

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

sortable.on(eventName: String, listener: Function): Sortable Sortable uses Draggables event emitter, so you can register callbacks for events. Sortable also supports method chaining.

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

sortable.trigger(eventName: String, event: AbstractEvent): Sortable You can trigger events through sortable. This is used to fire events internally or by extensions of Draggable.

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

Options

Same as Draggable

Events

Classes

Same as Draggable

Example

This sample code will make list items draggable:

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

new Sortable(document.querySelectorAll('ul'))
  .on('sortable:start', () => console.log('sortable:start'))
  .on('sortable:sorted', () => console.log('sortable:sorted'))
  .on('sortable:stop', () => console.log('sortable:stop'));

Droppable

Droppable allows you to declare draggable and droppable elements via options.

Sortable allows you to reorder elements. It maintains the order internally and fires three events on top of the draggable events: sortable:start, sortable:sorted and sortable:stop.

API

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

droppable.on(eventName: String, listener: Function): Droppable Droppable uses Draggables event emitter, so you can register callbacks for events. Droppable also supports method chaining.

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

droppable.trigger(eventName: String, event: AbstractEvent): Droppable You can trigger events through droppable. This is used to fire events internally or by extensions of Draggable.

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

Options

droppable {String|Array[HTMLElement]|NodeList|Function} A css selector string, an array of elements, a NodeList or a function returning elements for droppable elements within the containers specified.

Events

Classes

Example

This sample code will make list items draggable and allows to drop them inside another element:

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

const droppable = new Droppable(document.querySelectorAll('ul'), {
  draggable: 'li',
  droppable: '#dropzone',
});

droppable.on('droppable:over', () => console.log('sortable:start'))
droppable.on('droppable:out', () => console.log('sortable:sorted'));

Swappable

Swappable allows you to swap elements by dragging over them. No order will be maintained (unlike Sortable), so any draggable element that gets dragged over will be swapped with the source element.

API

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

swappable.on(eventName: String, listener: Function): Swappable Swappable uses Draggables event emitter, so you can register callbacks for events. Swappable also supports method chaining.

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

swappable.trigger(eventName: String, event: AbstractEvent): Swappable You can trigger events through swappable. This is used to fire events internally or by extensions of Draggable.

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

Options

Same as Draggable

Events

Classes

Same as Draggable

Example

This sample code will make list items draggable and allows to drop them inside another element:

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

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

swappable.on('swappable:start', () => console.log('swappable:start'))
swappable.on('swappable:swapped', () => console.log('swappable:swapped'));
swappable.on('swappable:stop', () => console.log('swappable:stop'));

Plugins

Draggables ships with two optional plugins: Collidable & Snappable

Collidable

When you use the collidable plugin you can specify which elements you can't drag over and it will freeze the mirror movement for you.

Options

collidables {String|Array[HTMLElement]|NodeList|HTMLElement|Function} A css selector string, an array of elements, a NodeList, a HTMLElement or a function returning elements for collidable elements.

Events

Example

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

const draggable = new Draggable(document.querySelectorAll('ul'), {
  draggable: 'li',
  collidables: '.other-list',
  plugins: [Collidable]
});

draggable.on('collidable:in', () => console.log('collidable:in'))
draggable.on('collidable:out', () => console.log('collidable:out'));

Snappable

Snappable simulates a "snap" by hiding the mirror and removing the 'source:dragging' class from the source. It also sets the 'source:placed' class for potential drop animations.

Options

No options

Events

Example

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

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

draggable.on('snap:in', () => console.log('snap:in'))
draggable.on('snap:out', () => console.log('snap:out'));

Contributing

Contributions are more than welcome, the code base is still new and needs more love.

1. Clone the repo: git clone https://github.com/Shopify/draggable.git
2. cd draggable
3. yarn install or npm install
4. Run tests with yarn test or npm run test
5. Submit PR

Roadmap

The roadmap for the official release is still in the works. More to come

Copyright

Copyright (c) 2017 Shopify. See LICENSE.md for further details.