Draggable Widget

Categories: Interactions

Draggable Widgetversion added: 1.0

Description: Allow elements to be moved using the mouse.

QuickNavExamples

Options

Methods

Events

Make the selected elements draggable by mouse. If you want not just drag, but drag & drop, see the jQuery UI Droppable plugin, which provides a drop target for draggables.

Options

addClasses 

Type: Boolean
Default: true
If set to false, will prevent the ui-draggable class from being added. This may be desired as a performance optimization when calling .draggable() on hundreds of elements.

appendTo 

Type: jQuery or Element or Selector or String
Default: "parent"
Which element the draggable helper should be appended to while dragging.
Multiple types supported:
  • jQuery: A jQuery object containing the element to append the helper to.
  • Element: The element to append the helper to.
  • Selector: A selector specifying which element to append the helper to.
  • String: The string "parent" will cause the helper to be a sibling of the draggable.

axis 

Type: String
Default: false
Constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: "x", "y".

cancel 

Type: Selector
Default: "input,textarea,button,select,option"
Prevents dragging from starting on specified elements.

connectToSortable 

Type: Selector
Default: false
Allows the draggable to be dropped onto the specified sortables. If this option is used, a draggable can be dropped onto a sortable list and then becomes part of it. Note: The helper option must be set to "clone" in order to work flawlessly. Requires the jQuery UI Sortable plugin to be included.

containment 

Type: Selector or Element or String or Array
Default: false
Constrains dragging to within the bounds of the specified element or region.
Multiple types supported:
  • Selector: The draggable element will be contained to the bounding box of the first element found by the selector. If no element is found, no containment will be set.
  • Element: The draggable element will be contained to the bounding box of this element.
  • String: Possible values: "parent", "document", "window".
  • Array: An array defining a bounding box in the form [ x1, y1, x2, y2 ].

cursor 

Type: String
Default: "auto"
The CSS cursor during the drag operation.

cursorAt 

Type: Object
Default: false
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 }.

delay 

Type: Number
Default: 0
Time in milliseconds after mousedown until dragging should start. This option can be used to prevent unwanted drags when clicking on an element.

disabled 

Type: Boolean
Default: false
Disables the draggable if set to true.

distance 

Type: Number
Default: 1
Distance in pixels after mousedown the mouse must move before dragging should start. This option can be used to prevent unwanted drags when clicking on an element.

grid 

Type: Array
Default: false
Snaps the dragging helper to a grid, every x and y pixels. The array must be of the form [ x, y ].

handle 

Type: Selector or Element
Default: false
If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s).

helper 

Type: String or Function()
Default: "original"
Allows for a helper element to be used for dragging display.
Multiple types supported:
  • String: If set to "clone", then the element will be cloned and the clone will be dragged.
  • Function: A function that will return a DOMElement to use while dragging.

iframeFix 

Type: Boolean or Selector
Default: false
Prevent iframes from capturing the mousemove events during a drag. Useful in combination with the cursorAt option, or in any case where the mouse cursor may not be over the helper.
Multiple types supported:
  • Boolean: When set to true, transparent overlays will be placed over all iframes on the page.
  • Selector: Any iframes matching the selector will be covered by transparent overlays.

opacity 

Type: Number
Default: false
Opacity for the helper while being dragged.

refreshPositions 

Type: Boolean
Default: false
If set to true, all droppable positions are calculated on every mousemove. Caution: This solves issues on highly dynamic pages, but dramatically decreases performance.

revert 

Type: Boolean or String
Default: false
Whether the element should revert to its start position when dragging stops.
Multiple types supported:
  • Boolean: If set to true the element will always revert.
  • String: If set to "invalid", revert will only occur if the draggable has not been dropped on a droppable. For "valid", it's the other way around.

revertDuration 

Type: Number
Default: 500
The duration of the revert animation, in milliseconds. Ignored if the revert option is false.

scope 

Type: String
Default: "default"
Used to group sets of draggable and droppable items, in addition to droppable's accept option. A draggable with the same scope value as a droppable will be accepted by the droppable.

scroll 

Type: Boolean
Default: true
If set to true, container auto-scrolls while dragging.

scrollSensitivity 

Type: Number
Default: 20
Distance in pixels from the edge of the viewport after which the viewport should scroll. Distance is relative to pointer, not the draggable. Ignored if the scroll option is false.

scrollSpeed 

Type: Number
Default: 20
The speed at which the window should scroll once the mouse pointer gets within the scrollSensitivity distance. Ignored if the scroll option is false.

snap 

Type: Boolean or Selector
Default: false
Whether the element should snap to other elements.
Multiple types supported:
  • Boolean: When set to true, the element will snap to all other draggable elements.
  • Selector: A selector specifying which elements to snap to.

snapMode 

Type: String
Default: "both"
Determines which edges of snap elements the draggable will snap to. Ignored if the snap option is false. Possible values: "inner", "outer", "both".

snapTolerance 

Type: Number
Default: 20
The distance in pixels from the snap element edges at which snapping should occur. Ignored if the snap option is false.

stack 

Type: Selector
Default: false
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.

zIndex 

Type: Number
Default: false
Z-index for the helper while being dragged.

Methods

destroy()Returns: jQuery (plugin only)

Removes the draggable functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).draggable( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the draggable.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).draggable( "disable" );

enable()Returns: jQuery (plugin only)

Enables the draggable.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).draggable( "enable" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
$( ".selector" ).draggable( "option" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current draggable options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
$( ".selector" ).draggable( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the draggable option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).draggable( "option" );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the draggable.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).draggable( "option" );

widget()Returns: jQuery

Returns a jQuery object containing the draggable element.
  • This method does not accept any arguments.
Code examples:

Invoke the widget method:

1
 
$( ".selector" ).draggable( "widget" );

Events

create( event, ui )Type: draggablecreate

Triggered when the draggable is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the draggable with the create callback specified:

1
2
3
 
$( ".selector" ).draggable({
  create: function( event, ui ) {}
});

Bind an event listener to the draggablecreate event:

1
 
$( ".selector" ).on( "draggablecreate", function( event, ui ) {} );

drag( event, ui )Type: draggabledrag

Triggered while the mouse is moved during the dragging.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper that's being dragged.
    • position
      Type: Object
      Current CSS position of the helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the helper as { top, left } object.
Code examples:

Initialize the draggable with the drag callback specified:

1
2
3
 
$( ".selector" ).draggable({
  drag: function( event, ui ) {}
});

Bind an event listener to the draggabledrag event:

1
 
$( ".selector" ).on( "draggabledrag", function( event, ui ) {} );

start( event, ui )Type: draggablestart

Triggered when dragging starts.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper that's being dragged.
    • position
      Type: Object
      Current CSS position of the helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the helper as { top, left } object.
Code examples:

Initialize the draggable with the start callback specified:

1
2
3
 
$( ".selector" ).draggable({
  start: function( event, ui ) {}
});

Bind an event listener to the draggablestart event:

1
 
$( ".selector" ).on( "draggablestart", function( event, ui ) {} );

stop( event, ui )Type: draggablestop

Triggered when dragging stops.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper that's being dragged.
    • position
      Type: Object
      Current CSS position of the helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the helper as { top, left } object.
Code examples:

Initialize the draggable with the stop callback specified:

1
2
3
 
$( ".selector" ).draggable({
  stop: function( event, ui ) {}
});

Bind an event listener to the draggablestop event:

1
 
$( ".selector" ).on( "draggablestop", function( event, ui ) {} );

Example:

A simple jQuery UI Draggable

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>draggable demo</title>
  <link rel="stylesheet" href="./code.jquery.com/ui/1.8.24/themes/base/jquery-ui.css">
  <style>
  #draggable {
    width: 100px;
    height: 100px;
    background: #ccc;
  }
  </style>
  <script src="./code.jquery.com/jquery-1.8.2.js"></script>
  <script src="./code.jquery.com/ui/1.8.24/jquery-ui.js"></script>
</head>
<body>
 
<div id="draggable">Drag me</div>
 
<script>
$( "#draggable" ).draggable();
</script>
 
</body>
</html>

Demo: