type: interaction

release: N/A

status: in development

documentation: N/A

demo: http://view.jqueryui.com/interactions/demos/draggable/default.html

Note: This plugin is being rewritten for the 2.0 release. This documentation is about the rewrite, not the existing plugin.

TODOs:

provide backCompat for all existing options for 2.0, except for iframeFix, distance, delay, and addClasses
figure out how to implement right and bottom positioning

1 - Description:

Draggable is a behavior that you can assign to any element. The element can then be repositioned using the mouse or other pointing device, and when used with the Droppable component, can be dropped on a specific target. The visual and logical behavior can be configured to match a variety of use cases.

2 - Visual Design:

N/A

3 - Functional Specifications/Requirements:

Options

appendTo (various, default: null)

a selector or element to append the draggable (or helper) to during the drag

handle (various, default: null)

a selector or element that can be used to drag the element
if a handle is specified, it must be a descendant of the draggable element

helper (various, default: false)

a boolean

when set to false, the original element will be dragged and no helper will be generated
when set to true, a clone of the element will be dragged

NOTE: If the element or any descendants have IDs, they will be removed from the cloned helper

a function

must return a jQuery object or DOMElement to use as the helper
TODO: figure out the signature for this

exclude (string, default: "input,textarea,button,select")

renamed from cancel

disabled (boolean, default: false)

when disabled, the draggable will not drag

containment (selector, default: null)

when specified, an element beyond which the dragged element shall not move.

Methods

refresh
----
disable
enable
destroy
option
widget

Events

beforeStart

triggered before the dragging interaction begins
can be cancelled to prevent the draggable from being activated
can modify ui.position to change where the element will start form
ui object

position { left, top } - CSS position of draggable element
offset { left, top } - offset of draggable element
pointer { x, y } - pointer position
helper, if there is one ( jQuery object ) - the helper that is being dragged instead of the original element

start

triggered when the dragging interaction begins
ui object:

originalPosition { left, top } - CSS position of draggable element when the drag started
originalOffset { left, top } - offset of draggable element when the drag started
originalPointer { x, y } - pointer position when the drag started
position { left, top } - current CSS position of draggable element
offset { left, top } - current offset of draggable element
pointer { x, y } - pointer position
helper, if there is one ( jQuery object )

drag

triggered for every movement during drag
can be cancelled to prevent the movement from occurring
can modify ui.position to change where the element will be moved
ui object:

originalPosition { left, top }
originalOffset { left, top }
originalPointer { x, y }
position { left, top }
offset { left, top }
pointer { x, y }
helper, if there is one ( jQuery object )

stop

triggered when the user has finished dragging the element
can be cancelled to prevent the helper (if there is one) from being destroyed
ui object:

originalPosition { left, top }
originalOffset { left, top }
originalPointer { x, y }
position { left, top }
offset { left, top }
pointer { x, y }
helper, if there is one ( jQuery object )

create

4 - Markup & Style:

4.1 Initial markup examples

(not applicable)

4.2 Recommended transformed HTML markup

(not applicable)

4.3 Accessibility recommendation

(Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices)

Draggable