Creates new draggables on the nodeset supplied by the query.
This jQuery plugin makes DOM nodes draggable by mouse. You can additionally supply a great range of options to make them fit your needs.
All callbacks (start,stop,drag) receive two arguments: The original browser event and a prepared ui object, view below for a documentation of this object (if you name your second argument 'ui'):
- ui.options - options used to initialize the draggable
- ui.helper - the JQuery object representing the helper that's being dragged
- ui.position - current position of the helper as { top, left } object, relative to the offset element
- ui.absolutePosition - current absolute position of the helper as { top, left } object, relative to page
Arguments:
| options | Options | |
|---|---|---|
| A set of key/value pairs that configure the draggable. All options are optional. | ||
Options:
| Name | Type | |
|---|---|---|
| appendTo | Element, Selector | Default: parent |
| For a draggable with a helper specified, the matched element passed to appendTo will be used as the helper's container. If not specified, the helper is appended to the same container as the draggable. | ||
| axis | String | Default: false |
| Constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: 'x', 'y'. | ||
| cancel | Selector | Default: ':input' |
| Prevents dragging if you start on elements matching the selector. | ||
| containment | Element, Selector | |
| Constrains dragging to within the bounds of the specified element - can be a DOM element, 'parent', 'document' or a jQuery selector. | ||
| cursor | String | Default: 'default' |
| The css cursor for the helper during the drag operation. | ||
| connectToSortable | Array, Selector | Default: false |
| An Array with comma seperated selector strings that match sortable lists, for example ["div ul", "ul.myclass"], or alternatively a jQuery selector. The better choice is the Array, if the selection needs to be dynamic (i.e. at a later point, more/less lists match the selector). If this option is used (helper must be set to clone in order to work flawlessly), a draggable can be dragged onto a sortable list and then becomes part of it. | ||
| cursorAt | Object, Array | |
| Moves the dragging element/helper so the cursor always appears to drag from the same position. Coordinates can be given as a hash using a combination of the keys top, left, right, bottom. | ||
| delay | Integer | Default: 0 |
| Time in milliseconds to define when the dragging should start. It helps preventing unwanted drags when clicking on an element. | ||
| distance | Integer | Default: 1 |
| Tolerance, in pixels, for when dragging should start. If specified, dragging will not start until after mouse is dragged beyond distance. | ||
| grid | [Integer x, Integer y] | |
| Snaps the dragging element/helper to a grid, every x and y pixels. | ||
| handle | Element, Selector | |
| Restricts drag start click to the specified element. Default value: draggable element. | ||
| helper | String, Function | Default: 'original' |
| Allows for a helper element to be used for dragging display. The 'clone' option will produce the 'ghosting' effect. Possible values: 'original', 'clone', Function. If you supply a function, it must return a valid DOM node. | ||
| iframeFix | String, Boolean | Default: false |
| Only useful in combination with cursorAt, or in any case, if the mouse cursor is not over the helper. It creates transparent overlays for all iframes on the page (if set to true, can be used to match certain iframes only if a selector is used) that are overlayed during the drag, so you can safely mouseover them without releasing the event. | ||
| opacity | Float | Default: 1.0 |
| Opacity for the helper while being dragged. | ||
| refreshPositions | 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 | Boolean | Default: false |
| If set to true, the element will return to its start position when dragging stops. Also accepts the strings "valid" and "invalid": 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 | Integer | Default: 500 |
| The duration of the revert animation. Since version 1.6 stable. | ||
| scroll | Boolean | Default: false |
| If true, container auto-scrolls while dragging. | ||
| scrollSensitivity | Integer | Default: 20 |
| Distance in pixels from the edge of the view port after which the view port should scroll. Distance is relative to pointer, not the draggable. | ||
| scrollSpeed | Integer | Default: 20 |
| The speed at which the window should scroll once the mouse pointer gets within the scrollSensitivity distance. | ||
| scope | String | Default: 'default' |
| Only useful if you have large collections of droppables. It's like an identifier that says what droppables a draggable can be dropped on. Must be set for both the draggable and the related droppables, works as addition to the droppable's accept option. | ||
| snap | Boolean,Selector | Default: false |
| If set to a selector or to true (same as selector ".ui-draggable"), the new draggable will snap to the edges of the selected elements when coming to an edge of the element. | ||
| snapMode | "inner","outer","both" | Default: 'both' |
| If set, the dragged element will only snap to the outer edges or to the inner edges of the element. | ||
| snapTolerance | Integer | Default: 20 |
| The distance in pixels from the snapping elements before the snapping should occur. | ||
| stack | Hash | Default: false |
| Controls the z-Index of the defined group (key 'group' in the hash, accepts jQuery selector) automatically, always brings to front the dragged item. Very useful in things like window managers. Optionally, a 'min' key can be set, so the zIndex cannot go below that value. | ||
| zIndex | Integer | |
| z-index for the helper while being dragged. | ||
| start | function(e, ui) | |
| Function that gets called when dragging starts. | ||
| drag | function(e, ui) | |
| Function that gets called when the mouse is moved during the dragging. | ||
| stop | function(e, ui) | |
| Function that gets called when dragging stops. | ||
Examples:
| Name | Type |
|---|