JqueryUI - Draggable
jQueryUI provides draggable() method to make any DOM element draggable. Once the element is draggable, you can move that element by clicking on it with the mouse and dragging it anywhere within the viewport.
Syntax
The draggable() method can be used in two forms −
$ (selector, context).draggable (options) Method
The draggable (options) method declares that an HTML element can be moved in the HTML page. The options parameter is an object that specifies the behavior of the elements involved.
Syntax
$(selector, context).draggable(options);
You can provide one or more options at a time using Javascript object. If there are more than one options to be provided then you will separate them using a comma as follows −
$(selector, context).draggable({option1: value1, option2: value2..... });
The following table lists the different options that can be used with this method −
| Sr.No. |
Option & Description |
| 1 |
addClasses
If this option is set to false, it will prevent the ui-draggable class from being added in the list of selected DOM elements. By default its value is true.
Option - addClasses
If this option is set to false, it will prevent the ui-draggable class from being added in the list of selected DOM elements. By default its value is true.
Syntax
$(".selector").draggable(
{ addClasses: false }
);
|
| 2 |
appendTo
Specifies the element in which the draggable helper should be appended to while dragging. By default its value is "parent".
Option - appendTo
Specifies the element in which the draggable helper should be appended to while dragging. By default its value is "parent".
Syntax
$(".selector").draggable(
{ appendTo: "body"}
);
|
| 3 |
axis
This option constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: "x", "y".
Option - axis
This option constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: "x", "y".
Syntax
$(".selector").draggable(
{ axis: "x" }
);
|
| 4 |
cancel
You can use this option to prevent dragging from starting on specified elements. By default its value is "input,textarea, button,select,option".
Option - cancel
You can use this option to prevent dragging from starting on specified elements. By default its value is "input,textarea, button,select,option"
Syntax
$(".selector").draggable(
{ cancel: ".title" }
);
|
| 5 |
connectToSortable
You can use this option to specify a list whose elements are interchangeable. At the end of placement, the element is part of the list. By default its value is "false".
Option - connectToSortable
You can use this option to specify a list whose elements are interchangeable. At the end of placement, the element is part of the list. By default its value is "false".
Syntax
$(".selector").draggable(
{ connectToSortable: "#my-sortable" }
);
|
| 6 |
containment
Constrains dragging to within the bounds of the specified element or region. By default its value is "false".
Option - containment
Constrains dragging to within the bounds of the specified element or region. By default its value is "false".
Syntax
$(".selector").draggable(
{ containment: "parent" }
);
|
| 7 |
cursor
Specifies the cursor CSS property when the element moves. It represents the shape of the mouse pointer. By default its value is "auto".
Option - cursor
Specifies the cursor CSS property when the element moves. It represents the shape of the mouse pointer. By default its value is "auto". Other possible values are −
- "crosshair" (across)
- "default" (an arrow)
- "pointer" (hand)
- "move" (two arrows cross)
- "e-resize" (expand to the right)
- "ne-resize" (expand up right)
- "nw-resize" (expand up left)
- "n-resize" (expand up)
- "se-resize" (expand down right)
- "sw-resize" (expand down left)
- "s-resize" (expand down)
- "auto" (default)
- "w-resize" (expand left)
- "text" (pointer to write text)
- "wait" (hourglass)
- "help" (help pointer)
Syntax
$(".selector").draggable(
{ cursor: "crosshair" }
);
|
| 8 |
cursorAt
Sets the offset of the dragging helper relative to the mouse cursor. Coordinates can be given as a hash using a combination of one or two keys: { top, left, right, bottom }. By default its value is "false".
Option - cursorAt
Sets the offset of the dragging helper relative to the mouse cursor. Coordinates can be given as a hash using a combination of one or two keys: { top, left, right, bottom }. By default its value is "false".
Syntax
$(".selector").draggable(
$( ".selector" ).draggable({ cursorAt: { left: 5 } });
);
|
| 9 |
delay
Delay, in milliseconds, after which the first movement of the mouse is taken into account. The displacement may begin after that time. By default its value is "0".
Option - delay
Delay, in milliseconds, after which the first movement of the mouse is taken into account. The displacement may begin after that time. By default its value is "0".
Syntax
$(".selector").draggable(
{ delay: 300 }
);
|
| 10 |
disabled
When set to true, disables the ability to move items. Items cannot be moved until this function is enabled (using the draggable ("enable") instruction). By default its value is "false".
Option - disabled
When set to true, disables the ability to move items. Items cannot be moved until this function is enabled (using the draggable ("enable") instruction). By default its value is "false".
Syntax
$(".selector").draggable(
{ disabled: true }
);
|
| 11 |
distance
Number of pixels that the mouse must be moved before the displacement is taken into account. By default its value is "1".
Option - distance
Number of pixels that the mouse must be moved before the displacement is taken into account. By default its value is "false".
Syntax
$(".selector").draggable(
{ distance: 10 }
);
|
| 12 |
grid
Snaps the dragging helper to a grid, every x and y pixels. The array must be of the form [ x, y ]. By default its value is "false".
Option - grid
Snaps the dragging helper to a grid, every x and y pixels. The array must be of the form [ x, y ]. By default its value is "false".
Syntax
$(".selector").draggable(
{ grid: [ 50, 20 ] }
);
|
| 13 |
handle
If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s). By default its value is "false".
Option - handle
If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s). By default its value is "false".
Syntax
$(".selector").draggable(
{ handle: "h2" }
);
|
| 14 |
helper
Allows for a helper element to be used for dragging display. By default its value is "original".
Option - helper
Allows for a helper element to be used for dragging display. By default its value is "original".
Syntax
$(".selector").draggable(
{ helper: "clone" }
);
|
| 15 |
iframeFix
Prevent iframes from capturing the mousemove events during a drag. By default its value is "false".
Option - iframeFix
Prevent iframes from capturing the mousemove events during a drag. By default its value is "false".
Syntax
$(".selector").draggable(
{ iframeFix: true }
);
|
| 16 |
opacity
Opacity of the element moved when moving. By default its value is "false".
Option - opacity
Opacity of the element moved when moving. By default its value is "false".
Syntax
$(".selector").draggable(
{ opacity: 0.35 }
);
|
| 17 |
refreshPositions
If set to true, all droppable positions are calculated on every mousemove. By default its value is "false".
Option - refreshPositions
If set to true, all droppable positions are calculated on every mousemove. By default its value is "false".
Syntax
$(".selector").draggable(
{ refreshPositions: true }
);
|
| 18 |
revert
Indicates whether the element is moved back to its original position at the end of the move. By default its value is "false".
Option - revert
Indicates whether the element is moved back to its original position at the end of the move. By default its value is "false".
Syntax
$(".selector").draggable(
{ revert: true }
);
|
| 19 |
revertDuration
Duration of displacement (in milliseconds) after which the element returns to its original position (see options.revert). By default its value is "500".
Option - revertDuration
Duration of displacement (in milliseconds) after which the element returns to its original position (see options.revert). By default its value is "500".
Syntax
$(".selector").draggable(
{ revertDuration: 200 }
);
|
| 20 |
scope
Used to group sets of draggable and droppable items, in addition to droppable's accept option. By default its value is "default".
Option - scope
Used to group sets of draggable and droppable items, in addition to droppable's accept option. By default its value is "default".
Syntax
$(".selector").draggable(
{ scope: "tasks" }
);
|
| 21 |
scroll
When set to true (the default), the display will scroll if the item is moved outside the viewable area of the window. By default its value is "true".
|
| 22 |
scrollSensitivity
Indicates how many pixels the mouse must exit the window to cause scrolling of the display. By default its value is "20".
|
| 23 |
scrollSpeed
Indicates the scrolling speed of the display once scrolling begins. By default its value is "20".
|
| 24 |
snap
Adjusts the display of the item being moved on other elements (which are flown). By default its value is "false".
Option - snap
Adjusts the display of the item being moved on other elements (which are flown). By default its value is "false".
Syntax
$(".selector").draggable(
{ snap: true }
);
|
| 25 |
snapMode
Specifies how the adjustment should be made between the moved element and those indicated in options.snap. By default its value is "both".
Option - snapMode
>Specifies how the adjustment should be made between the moved element and those indicated in options.snap. By default its value is "both".
Syntax
$(".selector").draggable(
{ snapMode: "inner" }
);
|
| 26 |
snapTolerance
Maximum number of pixels in the difference in position necessary to establish the adjustment. By default its value is "20".
Option - snapTolerance
Maximum number of pixels in the difference in position necessary to establish the adjustment. By default its value is "20".
Syntax
$(".selector").draggable(
{ snapTolerance: 30 }
);
|
| 27 |
stack
Controls the z-index of the set of elements that match the selector, always brings the currently dragged item to the front. Very useful in things like window managers. By default its value is "false".
Option - stack
Controls the z-index of the set of elements that match the selector, always brings the currently dragged item to the front. Very useful in things like window managers. By default its value is "false".
Syntax
$(".selector").draggable(
{ stack: ".products" }
);
|
| 28 |
zIndex
Z-index for the helper while being dragged. By default its value is "false".
Option - zIndex
Z-index for the helper while being dragged. By default its value is "false".
Syntax
$(".selector").draggable(
{ zIndex: 100 }
);
|
The following section will show you a few working examples of drag functionality.
Default functionality
The following example demonstrates a simple example of draggable functionality passing no parameters to the draggable() method.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<style>
#draggable { width: 150px; height: 150px; padding: 0.5em; background:#eee;}
</style>
<script>
$(function() {
$( "#draggable" ).draggable();
});
</script>
</head>
<body>
<div id = "draggable" class = "ui-widget-content">
<p>Drag me !!!</p>
</div>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser that supports javascript. You must also see the following output. Now, you can play with the result −
Use of Disable, Distance, and Delay
The following example shows the usage of three important options (a) disabled (b) delay and (c) distance in the drag function of JqueryUI.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<div id = "div1" style = "border:solid 1px;background-color:gainsboro;">
<span>You can't move me!</span><br /><br />
</div>
<div id = "div2" style = "border:solid 1px;background-color:grey;">
<span>
Dragging will start only after you drag me for 50px
</span>
<br /><br />
</div>
<div id = "div3" style = "border:solid 1px;background-color:gainsboro;">
<span>
You have to wait for 500ms for dragging to start!
</span>
<br /><br />
</div>
<script>
$("#div1 span").draggable (
{ disabled: true }
);
$("#div2 span").draggable (
{ distance: 50 }
);
$("#div3 span").draggable (
{ delay: 500 }
);
</script>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser that supports javascript, you should see the following output. Now, you can play with the result −
Constrain Movement
The following example shows how to limit the movement of elements on the screen using containment option in the drag function of JqueryUI.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<div id = "div4" style = "border:solid 1px;background-color:gainsboro;">
<span>You can drag me only within this div.</span><br /><br />
</div>
<div id = "div5" style = "border:solid 1px;background-color:grey;">
<span>You can drag me only along x axis.</span><br /><br />
</div>
<script>
$("#div4 span").draggable ({
containment : "#div4"
});
$("#div5 span").draggable ({
axis : "x"
});
</script>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser which supports javascript. It should produce the following output. Now, you can play with the output −
Here, <span> elements are prevented from going outside a <div> whose ID is div4. You can also impose constraints on vertical or horizontal motion using options axis worth "x" or "y", which is also demonstrated.
Move content by duplicating
The following example demonstrates how to move an item that is the clone of the selected element. This is done using the option helper with value clone.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<div id = "div6" style = "border:solid 1px;background:#eee; height:50px;">
<span>You can duplicate me....</span>
</div>
<script>
$("#div6 span").draggable ({
helper : "clone"
});
</script>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser which supports javascript, you must also see the following output −
As you can see when the first element is being dragged, only the cloned element moves, while the original item stays put. If you release the mouse, the cloned element disappears and the original item is still in its original position.
Get Current Option Value
The following example demonstrates how you can get a value of any option at any time during your script execution. Here we will read the value of cursor and cursorAt options set at the time of execution. Similar way you can get value of any other options available.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<div id = "divX" style = "border:solid 1px;background:#eee; height:50px;">
<span>Click anywhere on me to see cursor type...</span>
</div>
<script>
/* First make the item draggable */
$("#divX span").draggable();
$("#divX span").bind('click', function( event ) {
var cursor = $( "#divX span" ).draggable( "option", "cursor" );
var cursorAt = $( "#divX span" ).draggable( "option", "cursorAt" );
alert("Cursor type - " + cursor + ", cursorAt - " + cursorAt);
});
</script>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser which supports javascript, you must also see the following output −
$ (selector, context).draggable ("action", [params]) Method
The draggable (action, params) method can perform an action on the movable elements, such as to prevent displacement. The action is specified as a string in the first argument and optionally, one or more params can be provided based on the given action.
Basically, Here actions are nothing but they are jQuery methods which we can use in the form of string.
Syntax
$(selector, context).draggable ("action", [params]);
The following table lists the actions for this method −
| Sr.No. |
Action & Description |
| 1 |
destroy()
Remove drag functionality completely. The elements are no longer movable. This will return the element back to its pre-init state.
Action - destroy()
Remove drag functionality completely. The elements are no longer movable. This will return the element back to its pre-init state.
Syntax
$(".selector").draggable("destroy");
|
| 2 |
disable()
Disable drag functionality. Elements cannot be moved until the next call to the draggable("enable") method.
Action - disable()
Disable drag functionality. Elements cannot be moved until the next call to the draggable("enable") method.
Syntax
$(".selector").draggable("disable");
|
| 3 |
enable()
Reactivates drag management. The elements can be moved again.
Action - enable()
Reactivates drag management. The elements can be moved again.
Syntax
$(".selector").draggable("enable");
|
| 4 |
option(optionName)
Gets the value currently associated with the specified optionName. Where optionName is name of the option to get and is of type String.
Action - option(optionName)
Gets the value currently associated with the specified optionName. Where optionName is name of the option to get and is of type String.
Syntax
var isDisabled = $( ".selector" ).draggable( "option", "disabled" );
|
| 5 |
option()
Gets an object containing key/value pairs representing the current draggable options hash.
Action - option()
Gets an object containing key/value pairs representing the current draggable options hash.
Syntax
var options = $( ".selector" ).draggable( "option" );
|
| 6 |
option(optionName, value)
Sets the value of the draggable option associated with the specified optionName. Where optionName is the name of the option to set and value is the value to set for the option.
Action - option(optionName, value)
Sets the value of the draggable option associated with the specified optionName. Where optionName is the name of the option to set and value is the value to set for the option.
Syntax
$( ".selector" ).draggable( "option", "disabled", true );
|
| 7 |
option(options)
Sets one or more options for the draggable. Where options is a map of option-value pairs to set.
Action - option(options)
Sets one or more options for the draggable. Where options is a map of option-value pairs to set.
Syntax
$(".selector").draggable("option", { disabled: true } );
|
| 8 |
widget()
Returns a jQuery object containing the draggable element.
|
Example
Now let us see an example using the actions from the above table. The following example demonstrates the use of actions disable and enable.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<div id = "div7" style = "border:solid 1px;background-color:gainsboro;">
<span>You can't move me. Dragging is disabled.</span><br><br>
</div>
<div id = "div8" style = "border:solid 1px;background-color:grey;">
<span>You can move me. Dragging is enabled.</span><br><br>
</div>
<script>
$("#div7 span").draggable ();
$("#div7 span").draggable ('disable');
$("#div8 span").draggable ();
$("#div8 span").draggable ('enable');
</script>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser which supports javascript, you should see the following output −
As you can see first element is disabled and the second element's dragging is enabled which you can try to drag.
Event Management on the Moved elements
In addition to the draggable (options) method which we saw in the previous sections, JqueryUI provides event methods which gets triggered for a particular event. These event methods are listed below −
| Sr.No. |
Event Method & Description |
| 1 |
create(event, ui)
Triggered when the draggable is created. Where event is of type Event, and ui is of type Object.
Event - create(event, ui)
Triggered when the draggable is created. Where event is of type Event, and ui is of type Object.
Syntax
$(".selector").draggable(
create: function(event, ui) {}
);
|
| 2 |
drag(event, ui)
Triggered while the mouse is moved during the dragging. Where event is of type Event, and ui is of type Object like helper, position, offset.
Event - drag(event, ui)
Triggered while the mouse is moved during the dragging. Where event is of type Event, and ui is of type Object like helper, position, offset.
Syntax
$(".selector").draggable(
drag: function(event, ui) {}
);
|
| 3 |
start(event, ui)
Triggered when dragging starts. Where event is of type Event, and ui is of type Object like helper, position, offset.
Event - start(event, ui)
Triggered when dragging starts. Where event is of type Event, and ui is of type Object like helper, position, offset.
Syntax
$(".selector").draggable(
start: function( event, ui ) {}
);
|
| 4 |
stop(event, ui)
Triggered when dragging stops. Where event is of type Event, and ui is of type Object like helper, position, offset.
Event - stop(event, ui)
Triggered when dragging stops. Where event is of type Event, and ui is of type Object like helper, position, offset.
Syntax
$(".selector").draggable(
stop: function( event, ui ) {}
);
|
Example
The following example demonstrates the use of event method during drag functionality. This example demonstrates use of drag event.
<!DOCTYPE html>
<html>
<head>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<div id = "div9" style = "border:solid 1px;background-color:gainsboro;">
<span>Drag me to check the event method firing</span><br /><br />
</div>
<script>
$("#div9 span").draggable ({
cursor: "move",
axis : "x",
drag: function( event, ui ) {
alert("hi..");
}
});
</script>
</body>
</html>
Let us save the above code in an HTML file dragexample.htm and open it in a standard browser which supports javascript, you should the following output −
Now try to drag the written content and you will see that start of a drag event gets fired which results in showing a dialogue box and cursor will change to move icon and text will move in X-axis only.
