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
• $(selector, context).draggable ("action", [params]) Method

$ (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.
2	appendTo Specifies the element in which the draggable helper should be appended to while dragging. By default its value is "parent".
3	axis This option constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: "x", "y".
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".
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".
6	containment Constrains dragging to within the bounds of the specified element or region. By default its value is "false".
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".
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".
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".
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".
11	distance Number of pixels that the mouse must be moved before the displacement is taken into account. By default its value is "1".
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".
13	handle If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s). By default its value is "false".
14	helper Allows for a helper element to be used for dragging display. By default its value is "original".
15	iframeFix Prevent iframes from capturing the mousemove events during a drag. By default its value is "false".
16	opacity Opacity of the element moved when moving. By default its value is "false".
17	refreshPositions If set to true, all droppable positions are calculated on every mousemove. By default its value is "false".
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".
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".
20	scope Used to group sets of draggable and droppable items, in addition to droppable's accept option. By default its value is "default".
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".
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".
26	snapTolerance Maximum number of pixels in the difference in position necessary to establish the adjustment. By default its value is "20".
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".
28	zIndex Z-index for the helper while being dragged. By default its value is "false".

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.
2	disable() Disable drag functionality. Elements cannot be moved until the next call to the draggable("enable") method.
3	enable() Reactivates drag management. The elements can be moved again.
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.
5	option() Gets an object containing key/value pairs representing the current draggable options hash.
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.
7	option(options) Sets one or more options for the draggable. Where options is a map of option-value pairs to set.
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.
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.
3	start(event, ui) Triggered when dragging starts. Where event is of type Event, and ui is of type Object like helper, position, offset.
4	stop(event, ui) Triggered when dragging stops. Where event is of type Event, and ui is of type Object like helper, position, offset.

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.