- ×
Drag and drop so simple it hurts
Browser support includes every sane browser and IE7+. (Granted you polyfill the functional
Array
methods in ES5)Framework support includes vanilla JavaScript, Angular, and React.
- Official Angular bridge for
dragula
(demo) - Official Angular 2 bridge for
dragula
(demo) - Official React bridge for
dragula
(demo)
Demo
Try out the demo!
Inspiration
Have you ever wanted a drag and drop library that just works? That doesn't just depend on bloated frameworks, that has great support? That actually understands where to place the elements when they are dropped? That doesn't need you to do a zillion things to get it to work? Well, so did I!
Features
- Super easy to set up
- No bloated dependencies
- Figures out sort order on its own
- A shadow where the item would be dropped offers visual feedback
- Touch events!
- Seamlessly handles clicks without any configuration
Install
You can get it on npm.
npm install dragula --save
Or a CDN.
<script src='https://cdnjs.cloudflare.com/ajax/libs/dragula/$VERSION/dragula.min.js'></script>
If you're not using either package manager, you can use
dragula
by downloading the files in thedist
folder. We strongly suggest usingnpm
, though.Including the JavaScript
There's a caveat to
dragula
. You shouldn't include it in the<head>
of your web applications. It's bad practice to place scripts in the<head>
, and as suchdragula
makes no effort to support this use case.Place
dragula
in the<body>
, instead.Including the CSS!
There's a few CSS styles you need to incorporate in order for
dragula
to work as expected.You can add them by including
dist/dragula.css
ordist/dragula.min.css
in your document. If you're using Stylus, you can include the styles using the directive below.@import 'node_modules/dragula/dragula'
Usage
Dragula provides the easiest possible API to make drag and drop a breeze in your applications.
dragula(containers?, options?)
By default,
dragula
will allow the user to drag an element in any of thecontainers
and drop it in any other container in the list. If the element is dropped anywhere that's not one of thecontainers
, the event will be gracefully cancelled according to therevertOnSpill
andremoveOnSpill
options.Note that dragging is only triggered on left clicks, and only if no meta keys are pressed.
The example below allows the user to drag elements from
left
intoright
, and fromright
intoleft
.dragula([document.querySelector('#left'), document.querySelector('#right')]);
You can also provide an
options
object. Here's an overview of the default values.dragula(containers, { isContainer: function (el) { return false; // only elements in drake.containers will be taken into account }, moves: function (el, source, handle, sibling) { return true; // elements are always draggable by default }, accepts: function (el, target, source, sibling) { return true; // elements can be dropped in any of the `containers` by default }, invalid: function (el, handle) { return false; // don't prevent any drags from initiating by default }, direction: 'vertical', // Y axis is considered when determining where an element would be dropped copy: false, // elements are moved by default, not copied copySortSource: false, // elements in copy-source containers can be reordered revertOnSpill: false, // spilling will put the element back where it was dragged from, if this is true removeOnSpill: false, // spilling will `.remove` the element, if this is true mirrorContainer: document.body, // set the element that gets mirror elements appended ignoreInputTextSelection: true, // allows users to select input text, see details below slideFactorX: 0, // allows users to select the amount of movement on the X axis before it is considered a drag instead of a click slideFactorY: 0, // allows users to select the amount of movement on the Y axis before it is considered a drag instead of a click });
You can omit the
containers
argument and add containers dynamically later on.var drake = dragula({ copy: true }); drake.containers.push(container);
You can also set the
containers
from theoptions
object.var drake = dragula({ containers: containers });
And you could also not set any arguments, which defaults to a drake without containers and with the default options.
var drake = dragula();
The options are detailed below.
options.containers
Setting this option is effectively the same as passing the containers in the first argument to
dragula(containers, options)
.options.isContainer
Besides the containers that you pass to
dragula
, or the containers you dynamicallypush
orunshift
from drake.containers, you can also use this method to specify any sort of logic that defines what is a container for this particulardrake
instance.The example below dynamically treats all DOM elements with a CSS class of
dragula-container
as dragula containers for thisdrake
.var drake = dragula({ isContainer: function (el) { return el.classList.contains('dragula-container'); } });
options.moves
You can define a
moves
method which will be invoked with(el, source, handle, sibling)
whenever an element is clicked. If this method returnsfalse
, a drag event won't begin, and the event won't be prevented either. Thehandle
element will be the original click target, which comes in handy to test if that element is an expected "drag handle".options.accepts
You can set
accepts
to a method with the following signature:(el, target, source, sibling)
. It'll be called to make sure that an elementel
, that came from containersource
, can be dropped on containertarget
before asibling
element. Thesibling
can benull
, which would mean that the element would be placed as the last element in the container. Note that ifoptions.copy
is set totrue
,el
will be set to the copy, instead of the originally dragged element.Also note that the position where a drag starts is always going to be a valid place where to drop the element, even if
accepts
returnedfalse
for all cases.options.copy
If
copy
is set totrue
(or a method that returnstrue
), items will be copied rather than moved. This implies the following differences:Event Move Copy drag
Element will be concealed from source
Nothing happens drop
Element will be moved into target
Element will be cloned into target
remove
Element will be removed from DOM Nothing happens cancel
Element will stay in source
Nothing happens If a method is passed, it'll be called whenever an element starts being dragged in order to decide whether it should follow
copy
behavior or not. Consider the following example.copy: function (el, source) { return el.className === 'you-may-copy-us'; }
options.copySortSource
If
copy
is set totrue
(or a method that returnstrue
) andcopySortSource
istrue
as well, users will be able to sort elements incopy
-source containers.copy: true, copySortSource: true
options.revertOnSpill
By default, spilling an element outside of any containers will move the element back to the drop position previewed by the feedback shadow. Setting
revertOnSpill
totrue
will ensure elements dropped outside of any approved containers are moved back to the source element where the drag event began, rather than stay at the drop position previewed by the feedback shadow.options.removeOnSpill
By default, spilling an element outside of any containers will move the element back to the drop position previewed by the feedback shadow. Setting
removeOnSpill
totrue
will ensure elements dropped outside of any approved containers are removed from the DOM. Note thatremove
events won't fire ifcopy
is set totrue
.options.direction
When an element is dropped onto a container, it'll be placed near the point where the mouse was released. If the
direction
is'vertical'
, the default value, the Y axis will be considered. Otherwise, if thedirection
is'horizontal'
, the X axis will be considered.options.invalid
You can provide an
invalid
method with a(el, handle)
signature. This method should returntrue
for elements that shouldn't trigger a drag. Thehandle
argument is the element that was clicked, whileel
is the item that would be dragged. Here's the default implementation, which doesn't prevent any drags.function invalidTarget (el, handle) { return false; }
Note that
invalid
will be invoked on the DOM element that was clicked and every parent up to immediate children of adrake
container.As an example, you could set
invalid
to returnfalse
whenever the clicked element (or any of its parents) is an anchor tag.invalid: function (el, handle) { return el.tagName === 'A'; }
options.mirrorContainer
The DOM element where the mirror element displayed while dragging will be appended to. Defaults to
document.body
.options.ignoreInputTextSelection
When this option is enabled, if the user clicks on an input element the drag won't start until their mouse pointer exits the input. This translates into the user being able to select text in inputs contained inside draggable elements, and still drag the element by moving their mouse outside of the input -- so you get the best of both worlds.
This option is enabled by default. Turn it off by setting it to
false
. If its disabled your users won't be able to select text in inputs withindragula
containers with their mouse.API
The
dragula
method returns a tiny object with a concise API. We'll refer to the API returned bydragula
asdrake
.drake.containers
This property contains the collection of containers that was passed to
dragula
when building thisdrake
instance. You canpush
more containers andsplice
old containers at will.drake.dragging
This property will be
true
whenever an element is being dragged.drake.start(item)
Enter drag mode without a shadow. This method is most useful when providing complementary keyboard shortcuts to an existing drag and drop solution. Even though a shadow won't be created at first, the user will get one as soon as they click on
item
and start dragging it around. Note that if they click and drag something else,.end
will be called before picking up the new item.drake.end()
Gracefully end the drag event as if using the last position marked by the preview shadow as the drop target. The proper
cancel
ordrop
event will be fired, depending on whether the item was dropped back where it was originally lifted from (which is essentially a no-op that's treated as acancel
event).drake.cancel(revert)
If an element managed by
drake
is currently being dragged, this method will gracefully cancel the drag action. You can also pass inrevert
at the method invocation level, effectively producing the same result as ifrevertOnSpill
wastrue
.Note that a "cancellation" will result in a
cancel
event only in the following scenarios.revertOnSpill
istrue
- Drop target (as previewed by the feedback shadow) is the source container and the item is dropped in the same position where it was originally dragged from
drake.remove()
If an element managed by
drake
is currently being dragged, this method will gracefully remove it from the DOM.drake.on
(Events)The
drake
is an event emitter. The following events can be tracked usingdrake.on(type, listener)
:Event Name Listener Arguments Event Description drag
el, source
el
was lifted fromsource
dragend
el
Dragging event for el
ended with eithercancel
,remove
, ordrop
drop
el, target, source, sibling
el
was dropped intotarget
before asibling
element, and originally came fromsource
cancel
el, container, source
el
was being dragged but it got nowhere and went back intocontainer
, its last stable parent;el
originally came fromsource
remove
el, container, source
el
was being dragged but it got nowhere and it was removed from the DOM. Its last stable parent wascontainer
, and originally came fromsource
shadow
el, container, source
el
, the visual aid shadow, was moved intocontainer
. May trigger many times as the position ofel
changes, even within the samecontainer
;el
originally came fromsource
over
el, container, source
el
is overcontainer
, and originally came fromsource
out
el, container, source
el
was dragged out ofcontainer
or dropped, and originally came fromsource
cloned
clone, original, type
DOM element original
was cloned asclone
, oftype
('mirror'
or'copy'
). Fired for mirror images and whencopy: true
drake.canMove(item)
Returns whether the
drake
instance can accept drags for a DOM elementitem
. This method returnstrue
when all the conditions outlined below are met, andfalse
otherwise.item
is a child of one of the specified containers fordrake
item
passes the pertinentinvalid
checksitem
passes amoves
check
drake.destroy()
Removes all drag and drop events used by
dragula
to manage drag and drop between thecontainers
. If.destroy
is called while an element is being dragged, the drag will be effectively cancelled.CSS
Dragula uses only four CSS classes. Their purpose is quickly explained below, but you can check
dist/dragula.css
to see the corresponding CSS rules.gu-unselectable
is added to themirrorContainer
element when dragging. You can use it to style themirrorContainer
while something is being dragged.gu-transit
is added to the source element when its mirror image is dragged. It just adds opacity to it.gu-mirror
is added to the mirror image. It handles fixed positioning andz-index
(and removes any prior margins on the element). Note that the mirror image is appended to themirrorContainer
, not to its initial container. Keep that in mind when styling your elements with nested rules, like.list .item { padding: 10px; }
.gu-hide
is a helper class to applydisplay: none
to an element.
Contributing
See contributing.markdown for details.
Support
We have a dedicated support channel in Slack. See this issue to get an invite. Support requests won't be handled through the repository.
License
MIT
- Official Angular bridge for