Web Development with jQuery (2015)

Draggable and Droppable Methods

Method

Description

Returns

draggable(options)

Makes the selected element(s) draggable. Options can be specified by passing an object literal as the first argument using key, value pairs. For a complete list of options, see the “Draggable Options” table later in this appendix.

jQuery

draggable('destroy')

Completely removes draggable functionality from the selected element(s).

jQuery

draggable('disable')

Disables draggable functionality on the selected element(s).

jQuery

draggable('enable')

Enables draggable functionality on the selected element(s).

jQuery

draggable('option')

Returns an object literal containing key, value pairs representing the value of each currently set option.

Object

draggable('option',option)

Returns the currently set value of the provided option name.

Mixed

draggable('option',option, value)

Sets the value of provided option to value.

jQuery

draggable('widget')

Returns a jQuery object containing the draggable element.

jQuery

droppable(options)

Makes the selected element(s) droppable. Options can be specified by passing an object literal as the first argument using key, value pairs. For a complete list of options, see the “Droppable Options” section later in this appendix.

Dropset

droppable('destroy')

Completely removes droppable functionality from the selected element(s).

jQuery

droppable('disable')

Disables droppable functionality on the selected element(s).

jQuery

droppable('enable')

Enables droppable functionality on the selected element(s).

jQuery

droppable('option')

Returns an object literal containing key, value pairs representing the value of each currently set option.

Object

droppable('option',option)

Returns the currently set value of the provided option name.

Mixed

droppable('option',option, value)

Sets the value of the provided option to value.

jQuery

droppable('widget')

Returns a jQuery object containing the droppable element.

jQuery

Draggable Options

Option

Description

Type

addClasses

If set to false, this option prevents the class ui-draggable from being added to the draggable element.
Default value: true

Boolean

appendTo

For a draggable with a helper option specified, the matched element passed to the appendTo option is used as the helper's container. If not specified, the helper is appended to the same container as the draggable.
Default value: "parent"

jQuery, Element, Selector, String

axis

Contains dragging to either the x or y axis.
Default value: false

String, Boolean

cancel

Prevents dragging, if you start dragging within elements matching the selector.
Default value: "input, textarea, button, select, option"
Default value: false

Selector

connectToSortable

Allows the draggable element to be dropped on the sortable elements specified in the provided selector.
Default value: false

Selector, Boolean

containment

Contains dragging within the bounds of the specified element or selection.
If a string is provided, the possible values are "window", "document", or "parent".
If an array is provided, the values represent the four coordinates of the containing box in the form of [x1, y1, x2, y2].
Default value: false

Element,
Selector,
String,
Array,
Boolean

cursor

The CSS cursor to be used during the operation. Any value suitable for use with the CSS cursor property may be provided.
Default value: "auto"

String

cursorAt

Moves the dragging element/helper, so the cursor always appears to drag from the same position. Coordinates can be given as an object literal using the keys: top, left, right, bottom.
Default value: false

Object,
Boolean

delay

Time in milliseconds (ms) to delay the start of a drag. This helps prevent unwanted dragging from occurring when clicking an element.
Default value: 0

Integer

disabled

Disables the draggable if set to true.
Default value: false

Boolean

distance

Tolerance in pixels for when dragging should start. Prevents dragging from taking place until the mouse cursor has reached the pixel distance from the point the drag began.
Default value: 1

Integer

grid

Snaps the dragging element or helper to a grid. The value is provided in the form of an array [x, y].
Default value: false

Array,
Boolean

handle

Restricts the drag start to the specified element. This lets you make a large element draggable, but only when a smaller element within it is used as the “handle.”
Default value: false

Element,
Selector

helper

Allows for a helper element to be used for dragging display. The clone option produces a ghosting effect. Possible values are original and clone. The default value is original. If you supply a function, it must return a valid DOM node.
Default value: "original"

String,
Function

iframeFix

Prevents an <iframe> from capturing mouse events. When set to true, all <iframe> elements are covered with a transparent overlay while dragging is taking place. If a selector is provided, only the <iframe> elements referenced by the selector are covered with a transparent overlay.
Default value: false

Boolean,
Selector

opacity

The CSS opacity for the element being dragged, specified as a float between 0 and 1.
Default value: false

Float,
Boolean

refreshPositions

By default, the positions of all droppable elements are cached and saved for reference for the best possible performance. Setting this option to true disables this caching, and the positions of droppable elements are recalculated in real time as the mouse moves.
Default value: false

Boolean

revert

If set to true, the element returns to its start position when dragging stops.
Also accepts the strings valid and invalid. If set to invalid, revert occurs only if the draggable has not been dropped on a droppable. If set to valid, it's the other way around.
If a function is provided, the function determines whether the element should be returned to its starting position. If you use a function, the function should return a boolean value.
Default value: false

Boolean,
String,
Function

revertDuration

The duration of the revert animation provided in milliseconds. This option is ignored if the revert option is false.
Default value: 500

Integer

scope

This option is used to group sets of draggable and droppable items. Used with the accept option on a droppable element, the scope option.
Default value: "default"

String

scroll

If set to true, the draggable's container auto-scrolls while dragging.
Default value: true

Boolean

scrollSensitivity

Distance in pixels from the edge of the viewport after which the viewport should scroll. Distance is relative to the pointer, not the draggable.
Default value: 20

Integer

scrollSpeed

The speed at which the window should scroll when the mouse pointer gets within the scrollSensitivity distance.
Default value: 20

Integer

snap

If set to a selector or to true (same as selector .ui-draggable), the new draggable snaps to the edges of the selected elements when coming to an edge of the element.
Default value: false

Boolean,
Selector

snapMode

If set, the dragged element snaps only to the outer edges or to the inner edges of the element. Possible values are inner, outer, and both.
Default value: "both"

String

snapTolerance

The distance in pixels from the snapping elements before the snapping should occur.
Default value: 20

Integer

stack

Used for window managers or window manger-like applications. This feature controls the z-index of draggable elements that match the provided selector. This feature ensures that the draggable element the user clicks on is always on top.
Default value: false

Selector,
Boolean

zIndex

The z-index value for the helper element, while it is being dragged.
Default value: false

Integer

Draggable Events

create

function(event, ui)

drag

A function that is executed while the element is being dragged.

function(event, ui)

start

A function that is executed when the element begins a drag.

function(event, ui)

stop

A function that is executed when the element's drag ends.

function(event, ui)

Option

Description

Type

ui.options

Options used to initialize the draggable element.

Object

ui.helper

The jQuery object representing the helper being dragged.

Object

ui.position

The current position of the helper as an object literal relative to the offset element.

Object {top, left}

ui.absolutePosition

The current absolute position of the helper relative to the page.

Object {top, left}

Droppable Options

Option

Description

Type

accept

If a function is provided, the function is executed each time a draggable is dropped on a droppable. This lets you filter which elements can be dropped. The function should return true if the dragged element should be accepted and false if it should not.
If a selector is provided, draggables that match the specified selector will be accepted by the droppable.
Default value: "*"

function(draggable)
Selector

activeClass

A class name that is added to the droppable element while a draggable element is being dragged.
Default value: false

String
Boolean

addClasses

If the value provided is set to false, this feature prevents the ui-droppable class name from being added to droppable elements.
Default value: true

Boolean

Disabled

Disables the droppable element if the value is set to true.
Default value: false

Boolean

greedy

If true, this property prevents event propagation on nested droppables.
Default value: false

Boolean

hoverClass

A class name that is added to the droppable element while a draggable element is being dragged over the droppable element.
Default value: false

String,
Boolean

scope

Used to group draggable and droppable elements into sets, with the accept option. Draggables and droppables can interact only with other draggables and droppables of the same scope.
Default value: "default"

String

tolerance

Specifies which method to use for determining whether a draggable element is over a droppable element. Possible values are fit, intersect, pointer, or touch.
Default value: "intersect"

String

Droppable Events

activate

A function that is executed any time an acceptable draggable element begins a drag.

function(event, ui)

create

A function that is executed when a droppable is created.

function(event, ui)

deactivate

A function that is executed any time an acceptable draggable element's drag ends.

function(event, ui)

Drop

A function that is executed when an accepted draggable element is dropped on a droppable element. (“On” is defined by the tolerance option.) Within the function, this refers to the droppable element, and ui.draggablerefers to the draggable element.

function(event, ui)

Out

A function that is executed when an acceptable draggable element leaves a droppable element. (“:eave” is defined by the tolerance option.)

function(event, ui)

Over

A function that is executed when an acceptable draggable element is dragged over a droppable element. (“Over” is defined by the tolerance option.)

function(event, ui)

Option

Description

Type

ui.options

The options used to initialize the droppable element.

Object

ui.position

The current position of the draggable helper.

Object {top, left}

ui.absolutePosition

The current absolute position of the draggable helper.

Object {top, left}

ui.draggable

The current draggable element.

Object

ui.helper

The current draggable helper.

Object