Draggable

Allow elements to be moved using the mouse.

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

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.

Code examples:

Initialize the draggable with the addClasses option specified:

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

Get or set the addClasses option, after initialization:

// Getter
var addClasses = $( ".selector" ).draggable( "option", "addClasses" );
 
// Setter
$( ".selector" ).draggable( "option", "addClasses", false );

appendTo

Type: jQuery or Element or Selector or String

Default: "parent"

Which element the draggable helper should be appended to while dragging.

Note: The appendTo option only works when the helper option is set to not use the original element.

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:

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

Get or set the appendTo option, after initialization:

// Getter
var appendTo = $( ".selector" ).draggable( "option", "appendTo" );
 
// Setter
$( ".selector" ).draggable( "option", "appendTo", "body" );

axis

Type: 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:

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

Get or set the axis option, after initialization:

// Getter
var axis = $( ".selector" ).draggable( "option", "axis" );
 
// Setter
$( ".selector" ).draggable( "option", "axis", "x" );

cancel

Type: Selector

Default: "input,textarea,button,select,option"

Prevents dragging from starting on specified elements.

Code examples:

Initialize the draggable with the cancel option specified:

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

Get or set the cancel option, after initialization:

// Getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );
 
// Setter
$( ".selector" ).draggable( "option", "cancel", ".title" );

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.

Code examples:

Initialize the draggable with the connectToSortable option specified:

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

Get or set the connectToSortable option, after initialization:

// Getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );
 
// Setter
$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );

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 ].

Code examples:

Initialize the draggable with the containment option specified:

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

Get or set the containment option, after initialization:

// Getter
var containment = $( ".selector" ).draggable( "option", "containment" );
 
// Setter
$( ".selector" ).draggable( "option", "containment", "parent" );

cursor

Type: String

Default: "auto"

The CSS cursor during the drag operation.

Code examples:

Initialize the draggable with the cursor option specified:

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

Get or set the cursor option, after initialization:

// Getter
var cursor = $( ".selector" ).draggable( "option", "cursor" );
 
// Setter
$( ".selector" ).draggable( "option", "cursor", "crosshair" );

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 }.

Code examples:

Initialize the draggable with the cursorAt option specified:

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

Get or set the cursorAt option, after initialization:

// Getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );
 
// Setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );

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.

Code examples:

Initialize the draggable with the delay option specified:

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

Get or set the delay option, after initialization:

// Getter
var delay = $( ".selector" ).draggable( "option", "delay" );
 
// Setter
$( ".selector" ).draggable( "option", "delay", 300 );

disabled

Type: Boolean

Default: false

Disables the draggable if set to true.

Code examples:

Initialize the draggable with the disabled option specified:

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

Get or set the disabled option, after initialization:

// Getter
var disabled = $( ".selector" ).draggable( "option", "disabled" );
 
// Setter
$( ".selector" ).draggable( "option", "disabled", 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.

Code examples:

Initialize the draggable with the distance option specified:

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

Get or set the distance option, after initialization:

// Getter
var distance = $( ".selector" ).draggable( "option", "distance" );
 
// Setter
$( ".selector" ).draggable( "option", "distance", 10 );

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 ].

Code examples:

Initialize the draggable with the grid option specified:

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

Get or set the grid option, after initialization:

// Getter
var grid = $( ".selector" ).draggable( "option", "grid" );
 
// Setter
$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );

handle

Type: Selector or Element

Default: false

If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s). Only elements that descend from the draggable element are permitted.

Code examples:

Initialize the draggable with the handle option specified:

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

Get or set the handle option, after initialization:

// Getter
var handle = $( ".selector" ).draggable( "option", "handle" );
 
// Setter
$( ".selector" ).draggable( "option", "handle", "h2" );

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.

Code examples:

Initialize the draggable with the helper option specified:

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

Get or set the helper option, after initialization:

// Getter
var helper = $( ".selector" ).draggable( "option", "helper" );
 
// Setter
$( ".selector" ).draggable( "option", "helper", "clone" );

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.

Code examples:

Initialize the draggable with the iframeFix option specified:

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

Get or set the iframeFix option, after initialization:

// Getter
var iframeFix = $( ".selector" ).draggable( "option", "iframeFix" );
 
// Setter
$( ".selector" ).draggable( "option", "iframeFix", true );

opacity

Type: Number

Default: false

Opacity for the helper while being dragged.

Code examples:

Initialize the draggable with the opacity option specified:

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

Get or set the opacity option, after initialization:

// Getter
var opacity = $( ".selector" ).draggable( "option", "opacity" );
 
// Setter
$( ".selector" ).draggable( "option", "opacity", 0.35 );

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.

Code examples:

Initialize the draggable with the refreshPositions option specified:

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

Get or set the refreshPositions option, after initialization:

// Getter
var refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" );
 
// Setter
$( ".selector" ).draggable( "option", "refreshPositions", true );

revert

Type: Boolean or String or Function()

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.
Function: A function to determine whether the element should revert to its start position. The function must return true to revert the element.

Code examples:

Initialize the draggable with the revert option specified:

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

Get or set the revert option, after initialization:

// Getter
var revert = $( ".selector" ).draggable( "option", "revert" );
 
// Setter
$( ".selector" ).draggable( "option", "revert", true );

revertDuration

Type: 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:

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

Get or set the revertDuration option, after initialization:

// Getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );
 
// Setter
$( ".selector" ).draggable( "option", "revertDuration", 200 );

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.

Code examples:

Initialize the draggable with the scope option specified:

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

Get or set the scope option, after initialization:

// Getter
var scope = $( ".selector" ).draggable( "option", "scope" );
 
// Setter
$( ".selector" ).draggable( "option", "scope", "tasks" );

scroll

Type: Boolean

Default: true

If set to true, container auto-scrolls while dragging.

Code examples:

Initialize the draggable with the scroll option specified:

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

Get or set the scroll option, after initialization:

// Getter
var scroll = $( ".selector" ).draggable( "option", "scroll" );
 
// Setter
$( ".selector" ).draggable( "option", "scroll", false );

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.

Code examples:

Initialize the draggable with the scrollSensitivity option specified:

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

Get or set the scrollSensitivity option, after initialization:

// Getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );
 
// Setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );

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.

Code examples:

Initialize the draggable with the scrollSpeed option specified:

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

Get or set the scrollSpeed option, after initialization:

// Getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );
 
// Setter
$( ".selector" ).draggable( "option", "scrollSpeed", 100 );

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.

Code examples:

Initialize the draggable with the snap option specified:

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

Get or set the snap option, after initialization:

// Getter
var snap = $( ".selector" ).draggable( "option", "snap" );
 
// Setter
$( ".selector" ).draggable( "option", "snap", true );

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".

Code examples:

Initialize the draggable with the snapMode option specified:

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

Get or set the snapMode option, after initialization:

// Getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );
 
// Setter
$( ".selector" ).draggable( "option", "snapMode", "inner" );

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.

Code examples:

Initialize the draggable with the snapTolerance option specified:

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

Get or set the snapTolerance option, after initialization:

// Getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );
 
// Setter
$( ".selector" ).draggable( "option", "snapTolerance", 30 );

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.

Code examples:

Initialize the draggable with the stack option specified:

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

Get or set the stack option, after initialization:

// Getter
var stack = $( ".selector" ).draggable( "option", "stack" );
 
// Setter
$( ".selector" ).draggable( "option", "stack", ".products" );

zIndex

Type: Number

Default: false

Z-index for the helper while being dragged.

Code examples:

Initialize the draggable with the zIndex option specified:

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

Get or set the zIndex option, after initialization:

// Getter
var zIndex = $( ".selector" ).draggable( "option", "zIndex" );
 
// Setter
$( ".selector" ).draggable( "option", "zIndex", 100 );

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:

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

disable()Returns: jQuery (plugin only)

Disables the draggable.

This method does not accept any arguments.

Code examples:

Invoke the disable method:

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

enable()Returns: jQuery (plugin only)

Enables the draggable.

This method does not accept any arguments.

Code examples:

Invoke the enable method:

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

instance()Returns: Object

Retrieves the draggable's instance object. If the element does not have an associated instance, undefined is returned.

Unlike other widget methods, instance() is safe to call on any element after the draggable plugin has loaded.

This method does not accept any arguments.

Code examples:

Invoke the instance method:

$( ".selector" ).draggable( "instance" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.

Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar" would get the value of the bar property on the foo option.

optionName

Type: String

The name of the option to get.

Code examples:

Invoke the method:

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:

var options = $( ".selector" ).draggable( "option" );

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

Sets the value of the draggable option associated with the specified optionName.

Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName. For example, "foo.bar" would update only the bar property of the foo option.

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:

$( ".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:

$( ".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:

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

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:

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

Bind an event listener to the dragcreate event:

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

drag( event, ui )Type: drag

Triggered while the mouse is moved during the dragging, immediately before the current move happens.

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. The values may be changed to modify where the element will be positioned. This is useful for custom containment, snapping, etc.
- offset
  
  Type: Object
  
  Current offset position of the helper as { top, left } object.

Code examples:

Initialize the draggable with the drag callback specified:

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

Bind an event listener to the drag event:

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

Constrain movement via ui.position:

$( ".selector" ).draggable({
  drag: function( event, ui ) {
 
    // Keep the left edge of the element
    // at least 100 pixels from the container
    ui.position.left = Math.min( 100, ui.position.left );
  }
});

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:

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

Bind an event listener to the dragstart event:

$( ".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:

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

Bind an event listener to the dragstop event:

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

Examples:

A simple jQuery UI Draggable

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>draggable demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css">
  <style>
  #draggable {
    width: 100px;
    height: 100px;
    background: #ccc;
  }
  </style>
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.11.4/jquery-ui.js"></script>
</head>
<body>
 
<div id="draggable">Drag me</div>
 
<script>
$( "#draggable" ).draggable();
</script>
 
</body>
</html>

Links:

http://api.jqueryui.com/draggable

doc_jQuery

2025-01-10 15:47:30

Comments