## Draggable Widget version added: 1.0

Description: Allow elements to be moved using the mouse.

## QuickNavExamples

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.

### Dependencies

- UI Core
- Widget Factory
- Mouse Interaction

## Options

### addClassesType: 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.
Code examples:

Initialize the draggable with the `addClasses` option specified:

1

    $( ".selector" ).draggable({ addClasses: false });

Get or set the `addClasses` option, after initialization:

1
2
3
4
5

    // gettervar addClasses = $( ".selector" ).draggable( "option", "addClasses" ); // setter$( ".selector" ).draggable( "option", "addClasses", false );

### appendToType: 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.

Code examples:

Initialize the draggable with the `appendTo` option specified:

1

    $( ".selector" ).draggable({ appendTo: "body" });

Get or set the `appendTo` option, after initialization:

1
2
3
4
5

    // gettervar appendTo = $( ".selector" ).draggable( "option", "appendTo" ); // setter$( ".selector" ).draggable( "option", "appendTo", "body" );

### axisType: String

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

Initialize the draggable with the `axis` option specified:

1

    $( ".selector" ).draggable({ axis: "x" });

Get or set the `axis` option, after initialization:

1
2
3
4
5

    // gettervar axis = $( ".selector" ).draggable( "option", "axis" ); // setter$( ".selector" ).draggable( "option", "axis", "x" );

### cancelType: Selector

Default: `"input,textarea,button,select,option"`
Prevents dragging from starting on specified elements.
Code examples:

Initialize the draggable with the `cancel` option specified:

1

    $( ".selector" ).draggable({ cancel: ".title" });

Get or set the `cancel` option, after initialization:

1
2
3
4
5

    // gettervar cancel = $( ".selector" ).draggable( "option", "cancel" ); // setter$( ".selector" ).draggable( "option", "cancel", ".title" );

### connectToSortableType: 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.
Code examples:

Initialize the draggable with the `connectToSortable` option specified:

1

    $( ".selector" ).draggable({ connectToSortable: "#my-sortable" });

Get or set the `connectToSortable` option, after initialization:

1
2
3
4
5

    // gettervar connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" ); // setter$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );

### containmentType: 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 ]`.

Code examples:

Initialize the draggable with the `containment` option specified:

1

    $( ".selector" ).draggable({ containment: "parent" });

Get or set the `containment` option, after initialization:

1
2
3
4
5

    // gettervar containment = $( ".selector" ).draggable( "option", "containment" ); // setter$( ".selector" ).draggable( "option", "containment", "parent" );

### cursorType: String

Default: `"auto"`
The CSS cursor during the drag operation.
Code examples:

Initialize the draggable with the `cursor` option specified:

1

    $( ".selector" ).draggable({ cursor: "crosshair" });

Get or set the `cursor` option, after initialization:

1
2
3
4
5

    // gettervar cursor = $( ".selector" ).draggable( "option", "cursor" ); // setter$( ".selector" ).draggable( "option", "cursor", "crosshair" );

### cursorAtType: 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 }`.
Code examples:

Initialize the draggable with the `cursorAt` option specified:

1

    $( ".selector" ).draggable({ cursorAt: { left: 5 } });

Get or set the `cursorAt` option, after initialization:

1
2
3
4
5

    // gettervar cursorAt = $( ".selector" ).draggable( "option", "cursorAt" ); // setter$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );

### delayType: 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.
Code examples:

Initialize the draggable with the `delay` option specified:

1

    $( ".selector" ).draggable({ delay: 300 });

Get or set the `delay` option, after initialization:

1
2
3
4
5

    // gettervar delay = $( ".selector" ).draggable( "option", "delay" ); // setter$( ".selector" ).draggable( "option", "delay", 300 );

### disabledType: Boolean

Default: `false`
Disables the draggable if set to `true`.
Code examples:

Initialize the draggable with the `disabled` option specified:

1

    $( ".selector" ).draggable({ disabled: true });

Get or set the `disabled` option, after initialization:

1
2
3
4
5

    // gettervar disabled = $( ".selector" ).draggable( "option", "disabled" ); // setter$( ".selector" ).draggable( "option", "disabled", true );

### distanceType: 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.
Code examples:

Initialize the draggable with the `distance` option specified:

1

    $( ".selector" ).draggable({ distance: 10 });

Get or set the `distance` option, after initialization:

1
2
3
4
5

    // gettervar distance = $( ".selector" ).draggable( "option", "distance" ); // setter$( ".selector" ).draggable( "option", "distance", 10 );

### gridType: Array

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

Initialize the draggable with the `grid` option specified:

1

    $( ".selector" ).draggable({ grid: [ 50, 20 ] });

Get or set the `grid` option, after initialization:

1
2
3
4
5

    // gettervar grid = $( ".selector" ).draggable( "option", "grid" ); // setter$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );

### handleType: Selector or Element

Default: `false`
If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s).
Code examples:

Initialize the draggable with the `handle` option specified:

1

    $( ".selector" ).draggable({ handle: "h2" });

Get or set the `handle` option, after initialization:

1
2
3
4
5

    // gettervar handle = $( ".selector" ).draggable( "option", "handle" ); // setter$( ".selector" ).draggable( "option", "handle", "h2" );

### helperType: 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.

Code examples:

Initialize the draggable with the `helper` option specified:

1

    $( ".selector" ).draggable({ helper: "clone" });

Get or set the `helper` option, after initialization:

1
2
3
4
5

    // gettervar helper = $( ".selector" ).draggable( "option", "helper" ); // setter$( ".selector" ).draggable( "option", "helper", "clone" );

### iframeFixType: 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.

Code examples:

Initialize the draggable with the `iframeFix` option specified:

1

    $( ".selector" ).draggable({ iframeFix: true });

Get or set the `iframeFix` option, after initialization:

1
2
3
4
5

    // gettervar iframeFix = $( ".selector" ).draggable( "option", "iframeFix" ); // setter$( ".selector" ).draggable( "option", "iframeFix", true );

### opacityType: Number

Default: `false`
Opacity for the helper while being dragged.
Code examples:

Initialize the draggable with the `opacity` option specified:

1

    $( ".selector" ).draggable({ opacity: 0.35 });

Get or set the `opacity` option, after initialization:

1
2
3
4
5

    // gettervar opacity = $( ".selector" ).draggable( "option", "opacity" ); // setter$( ".selector" ).draggable( "option", "opacity", 0.35 );

### refreshPositionsType: 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.
Code examples:

Initialize the draggable with the `refreshPositions` option specified:

1

    $( ".selector" ).draggable({ refreshPositions: true });

Get or set the `refreshPositions` option, after initialization:

1
2
3
4
5

    // gettervar refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" ); // setter$( ".selector" ).draggable( "option", "refreshPositions", true );

### revertType: 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.

Code examples:

Initialize the draggable with the `revert` option specified:

1

    $( ".selector" ).draggable({ revert: true });

Get or set the `revert` option, after initialization:

1
2
3
4
5

    // gettervar revert = $( ".selector" ).draggable( "option", "revert" ); // setter$( ".selector" ).draggable( "option", "revert", true );

### revertDurationType: Number

Default: `500`
The duration of the revert animation, in milliseconds. Ignored if the `revert` option is `false`.
Code examples:

Initialize the draggable with the `revertDuration` option specified:

1

    $( ".selector" ).draggable({ revertDuration: 200 });

Get or set the `revertDuration` option, after initialization:

1
2
3
4
5

    // gettervar revertDuration = $( ".selector" ).draggable( "option", "revertDuration" ); // setter$( ".selector" ).draggable( "option", "revertDuration", 200 );

### scopeType: 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.
Code examples:

Initialize the draggable with the `scope` option specified:

1

    $( ".selector" ).draggable({ scope: "tasks" });

Get or set the `scope` option, after initialization:

1
2
3
4
5

    // gettervar scope = $( ".selector" ).draggable( "option", "scope" ); // setter$( ".selector" ).draggable( "option", "scope", "tasks" );

### scrollType: Boolean

Default: `true`
If set to `true`, container auto-scrolls while dragging.
Code examples:

Initialize the draggable with the `scroll` option specified:

1

    $( ".selector" ).draggable({ scroll: false });

Get or set the `scroll` option, after initialization:

1
2
3
4
5

    // gettervar scroll = $( ".selector" ).draggable( "option", "scroll" ); // setter$( ".selector" ).draggable( "option", "scroll", false );

### scrollSensitivityType: 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`.
Code examples:

Initialize the draggable with the `scrollSensitivity` option specified:

1

    $( ".selector" ).draggable({ scrollSensitivity: 100 });

Get or set the `scrollSensitivity` option, after initialization:

1
2
3
4
5

    // gettervar scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" ); // setter$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );

### scrollSpeedType: 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`.
Code examples:

Initialize the draggable with the `scrollSpeed` option specified:

1

    $( ".selector" ).draggable({ scrollSpeed: 100 });

Get or set the `scrollSpeed` option, after initialization:

1
2
3
4
5

    // gettervar scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" ); // setter$( ".selector" ).draggable( "option", "scrollSpeed", 100 );

### snapType: 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.

Code examples:

Initialize the draggable with the `snap` option specified:

1

    $( ".selector" ).draggable({ snap: true });

Get or set the `snap` option, after initialization:

1
2
3
4
5

    // gettervar snap = $( ".selector" ).draggable( "option", "snap" ); // setter$( ".selector" ).draggable( "option", "snap", true );

### snapModeType: 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"`.
Code examples:

Initialize the draggable with the `snapMode` option specified:

1

    $( ".selector" ).draggable({ snapMode: "inner" });

Get or set the `snapMode` option, after initialization:

1
2
3
4
5

    // gettervar snapMode = $( ".selector" ).draggable( "option", "snapMode" ); // setter$( ".selector" ).draggable( "option", "snapMode", "inner" );

### snapToleranceType: Number

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

Initialize the draggable with the `snapTolerance` option specified:

1

    $( ".selector" ).draggable({ snapTolerance: 30 });

Get or set the `snapTolerance` option, after initialization:

1
2
3
4
5

    // gettervar snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" ); // setter$( ".selector" ).draggable( "option", "snapTolerance", 30 );

### stackType: 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.
Code examples:

Initialize the draggable with the `stack` option specified:

1

    $( ".selector" ).draggable({ stack: ".products" });

Get or set the `stack` option, after initialization:

1
2
3
4
5

    // gettervar stack = $( ".selector" ).draggable( "option", "stack" ); // setter$( ".selector" ).draggable( "option", "stack", ".products" );

### zIndexType: Number

Default: `false`
Z-index for the helper while being dragged.
Code examples:

Initialize the draggable with the `zIndex` option specified:

1

    $( ".selector" ).draggable({ zIndex: 100 });

Get or set the `zIndex` option, after initialization:

1
2
3
4
5

    // gettervar zIndex = $( ".selector" ).draggable( "option", "zIndex" ); // setter$( ".selector" ).draggable( "option", "zIndex", 100 );

## 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

    var isDisabled = $( ".selector" ).draggable( "option", "disabled" );

### 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

    var options = $( ".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", "disabled", true );

### 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", { disabled: true } );

### 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

    var widget = $( ".selector" ).draggable( "widget" );

## Events

### create( event, ui )Type: `dragcreate`

Triggered when the draggable is created.

- event
  Type: Event
- ui
  Type: Object

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 dragcreate event:

1

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

### drag( event, ui )Type: `drag`

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 drag event:

1

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

### start( event, ui )Type: `dragstart`

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 dragstart event:

1

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

### stop( event, ui )Type: `dragstop`

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 dragstop event:

1

    $( ".selector" ).on( "dragstop", 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.9.2/themes/base/jquery-ui.css">  <style>  #draggable {    width: 100px;    height: 100px;    background: #ccc;  }  </style>  <script src="//code.jquery.com/jquery-1.8.3.js"></script>  <script src="//code.jquery.com/ui/1.9.2/jquery-ui.js"></script></head><body> <div id="draggable">Drag me</div> <script>$( "#draggable" ).draggable();</script> </body></html>

#### Demo: