Draggable

Draggable is the standard draggable units handling class from the drag-and-drop library.

The public API consists of only two methods: constructor and destructor. The constructor receives a reference to an element and the options hash while the destructor is just a method which detaches all the events handling from the element thus making it not draggable anymore.

// Make 'my-element' draggable ...
var draggable = new Draggable('my-element', {axis: 'x'});

// ... and remove the dragging ability again
draggable.destroy();

You can also use the auto-initialization feature and the Element level shortcuts to create draggables. See the main drag-and-drop page for more details.

Index

top ↑Options List

There are a number of options you can specify for your draggables:

NameDefaultDescription
handlenullreference to the handle element that will start the drag
snap0number in pixels or [x,y]
axisnullnull or ‘x’ or ‘y’ or ‘vertical’ or ‘horizontal’
rangenull{x: [min, max], y:[min, max]} or reference to another element
dragClass‘dragging’the dragging time class name
clonefalseshould a clone be kept in place?
revertfalseshould the object be moved back once dropped?
revertDuration‘normal’moving back fx duration
scrolltrueshould draggables automatically scroll the window?
scrollSensitivity32scrolling area size in pixels
zIndex10000000initial elements z-index (gets incremented during drags)
moveOutfalseshould the draggable be moved out of its context? (for overflown elements)
relName‘draggable’the auto-initialization feature key

As usual you can specify them as initialization options for every particular draggable unit or customize the Draggable.Options in order to change the global settings.

top ↑Events List

There are a few events to notify your application about draggables:

NameDescription
beforebefore any drag calculations
startwhen the drag starts
dragwhen the element changed its position
stopwhen the user released the element
dropwhen the object was dropped on a droppable object

All callbacks except 'drop' pass two arguments: the draggable itself and the mouse event that caused the event.

new Draggable('my-element', {
onStart: function(draggable, event) {
notify_my_application_about_drag_start();
}
});

The 'drop' event on the other hand is triggered only when the draggable was dropped on top of a droppable object that accepts it and once this happened the listener receives three arguments: the droppable object, the draggable object and the mouse event that caused the event.

new Draggable('my-element', {
onDrop: function(droppable, draggable, event) {
notify_my_app();
}
});

top ↑Relatively Positioned Draggables

This implementation of draggables works transparently with draggable elements located inside relatively positioned elements with their own positions scope:

<div style="position: absolute; left: 40em; top: 10em">
<div rel="draggable" style="left: 0; top:0">
Drag me around!
</div>
</div>

The only condition is that you must specify the default position of the element with CSS or the style attribute. Once you’ve done that, the script will check the relative and absolute positions of the element and whether they are different. If this condition is met, the draggable will work as expected inside the relative positions scope.