Draggable
Behaviours > Draggable
To make an element draggable, create a new instance of class Draggable.
For additional built-in functionality, make a Sortable instead.
There is also a class named Draggables that exposes functions for observing drag actions.
Draggables become much more useful when you use them with droppables, which are the areas that you can drag draggables to.
Syntax
new Draggable('id_of_element', [options]);
Options
| Option | Since | Description |
|---|---|---|
| handle | 1.0 | string or DOM reference, not set by default. Sets whether the element should only be draggable by an embedded handle. The value must be an element reference or element id. |
| handle | 1.5. | string or DOM reference, not set by default. As above, except now the value may be a string referencing a CSS class value. The first child/grandchild/etc. element found within the element that has this CSS class value will be used as the handle. |
| revert | 1.0 | boolean, defaults to false. If set to true, the element returns to its original position when the drags ends. |
| revert | 1.5 | boolean or function reference, defaults to false. Revert can also be an arbitrary function reference, called when the drag ends. Specifying 'failure' will instruct the draggable not to revert if successfully dropped in a droppable. |
| snap | 1.5 | If set to false no snapping occurs. Otherwise takes one of the following forms – Δi: one delta value for both horizontal and vertical snap, [Δx, Δy]: delta values for horizontal and vertical snap, function(x, y, draggable_object) { return [x, y]; }: a function that receives the proposed new top left coordinate pair and returns the coordinate pair to actually be used. |
| zindex | 1.5 | integer value, defaults to 1000. The css z-index of the draggable item. |
| constraint | 1.0 | string, not set by default. If set to 'horizontal' or 'vertical' the drag will be constrained to take place only horizontally or vertically. |
| ghosting | ?? | boolean, defaults to false. Clones the element and drags the clone, leaving the original in place until the clone is dropped. |
| starteffect | ?? | Effect, defaults to Effect.Opacity. Defines the effect to use when the draggable starts being dragged. |
| reverteffect | ?? | Effect, default to Effect.Move. Defines the effect to use when the draggable reverts back to its starting position. |
| endeffect | ?? | Effect, defaults to Effect.Opacity. Defines the effect to use when the draggable stops being dragged. |
| scroll | ?? | string or DOM reference, not set by default. Specifies the element which will scroll when you get to the boundary. By default this is turned off. |
| scrollSensitivity | ?? | integer value, defaults to 20 pixels. Minimum distance from the element boundary to start scrolling. |
Additionally, the options parameter accepts any of the following callback functions:
| Callback | Description |
|---|---|
| onStart | Called when a drag is initiated. |
| onDrag | Called repeatedly as the mouse moves, before the draggable position is updated if mouse position changed from previous call. |
| change | Called just as onDrag, but after the draggable position is updated. Gets the Draggable instance as its parameter. |
| onEnd | Called when a drag is ended. |
Except for the change callback, each of these callbacks accepts two parameters: the Draggable object, and the mouse event object.
Examples
// revert
new Draggable('product_1', { revert: true });
// constrain direction and give a handle
new Draggable('my_div', { constraint: 'horizontal', handle: 'handle' });
To disable draggables later on, store it in a variable like:
var mydrag = new Draggable('product_1', { revert: true });
// then destroy it when you don't need it anymore
mydrag.destroy();
This way, you can enable and disable dragging at will.
Demo
A demo with the default options
A demo with { revert: true, snap: [40, 40] } set as options
A demo with { scroll: window } set as options
Source code of the demo
Demo 1 (default options)
<div id="drag_demo_1" style="width:100px; height:100px; background:#7baaed; border:1px solid #333;"></div>
<script type="text/javascript">
new Draggable('drag_demo_1');
</script>
Demo 2 (with revert and snap set)
<div id="drag_demo_2" style="width:100px; height:100px; background:#fff85d; border:1px solid #333;"></div>
<script type="text/javascript">
new Draggable('drag_demo_2', { revert: true, snap: [40, 40] });
</script>
Demo 3 (with scroll set)
<div id="drag_demo_3" style="width:80px; height:80px; cursor:move; background:#88da5d; border:1px solid #333;"></div>
<script type="text/javascript">
new Draggable('drag_demo_3', { scroll: window });
</script>
