Categories

.draggable()

Categories: UI

.draggable( [ options ] )

Plugin: jQuery.ui.draggable

Description: Apply the Draggable widget for each element in the set of matched elements

  • .draggable( [ options ] )

    version added: 1.0

    options   A map of additional options pass to the widget.

The jQuery UI Draggable plugin makes selected elements draggable by mouse.

Draggable elements gets a class of ui-draggable. During drag the element also gets a class of ui-draggable-dragging. If you want not just drag, but drag-and-drop, see the jQuery UI Droppable plugin, which provides a drop target for draggables.

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.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.offset - current absolute position of the helper as { top, left } object, relative to page



To manipulate the position of a draggable during drag, you can either use a wrapper as the draggable helper and position the wrapped element with absolute positioning, or you can correct internal values like so: $(this).data('draggable').offset.click.top -= x.

  • disabled

    Disables (true) or enables (false) the draggable. Can be set when initialising (first creating) the draggable.

    Default: false

  • addClasses

    If set to false, will prevent the ui-draggable class from being added. This may be desired as a performance optimization when calling .draggable() init on many hundreds of elements.

    Default: true

  • appendTo

    The element passed to or selected by the appendTo option will be used as the draggable helper's container during dragging. By default, the helper is appended to the same container as the draggable.

    Default: 'parent'

  • axis

    Constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: 'x', 'y'.

    Default: false

  • cancel

    Prevents dragging from starting on specified elements.

    Default: ':input,option'

  • connectToSortable

    Allows the draggable to be dropped onto the specified sortables. If this option is used (helper must be set to 'clone' in order to work flawlessly), a draggable can be dropped onto a sortable list and then becomes part of it. Note: Specifying this option as an array of selectors has been removed.

    Default: false

  • containment

    Constrains dragging to within the bounds of the specified element or region. Possible string values: 'parent', 'document', 'window', [x1, y1, x2, y2].

    Default: false

  • cursor

    The css cursor during the drag operation.

    Default: 'auto'

  • cursorAt

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

    Default: false

  • delay

    Time in milliseconds after mousedown until dragging should start. This option can be used to prevent unwanted drags when clicking on an element.

  • distance

    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.

    Default: 1

  • grid

    Snaps the dragging helper to a grid, every x and y pixels. Array values: [x, y]

    Default: false

  • handle

    If specified, restricts drag start click to the specified element(s).

    Default: false

  • helper

    Allows for a helper element to be used for dragging display. Possible values: 'original', 'clone', Function. If a function is specified, it must return a DOMElement.

    Default: 'original'

  • iframeFix

    Prevent iframes from capturing the mousemove events during a drag. Useful in combination with cursorAt, or in any case, if the mouse cursor is not over the helper. If set to true, transparent overlays will be placed over all iframes on the page. If a selector is supplied, the matched iframes will have an overlay placed over them.

    Default: false

  • opacity

    Opacity for the helper while being dragged.

    Default: false

  • refreshPositions

    If set to true, all droppable positions are calculated on every mousemove. Caution: This solves issues on highly dynamic pages, but dramatically decreases performance.

    Default: false

  • revert

    If set to true, the element will return to its start position when dragging stops. Possible string values: 'valid', '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.

    Default: false

  • revertDuration

    The duration of the revert animation, in milliseconds. Ignored if revert is false.

    Default: 500

  • scope

    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.

    Default: 'default'

  • scroll

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

    Default: true

  • scrollSensitivity

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

    Default: 20

  • scrollSpeed

    The speed at which the window should scroll once the mouse pointer gets within the scrollSensitivity distance.

    Default: 20

  • snap

    If set to a selector or to true (equivalent to '.ui-draggable'), the draggable will snap to the edges of the selected elements when near an edge of the element.

    Default: false

  • snapMode

    Determines which edges of snap elements the draggable will snap to. Ignored if snap is false. Possible values: 'inner', 'outer', 'both'

    Default: 'both'

  • snapTolerance

    The distance in pixels from the snap element edges at which snapping should occur. Ignored if snap is false.

    Default: 20

  • stack

    Controls the z-Index of the set of elements that match the selector, always brings to front the dragged item. Very useful in things like window managers.

    Default: false

  • zIndex

    z-index for the helper while being dragged.

    Default: false

  • create

    This event is triggered when draggable is created.

  • start

    This event is triggered when dragging starts.

  • drag

    This event is triggered when the mouse is moved during the dragging.

  • stop

    This event is triggered when dragging stops.

  • destroy

    • .draggable( "destroy" )

      version added: 1.0

    Remove the draggable functionality completely. This will return the element back to its pre-init state.

  • disable

    • .draggable( "disable" )

      version added: 1.0

    Disable the draggable.

  • enable

    • .draggable( "enable" )

      version added: 1.0

    Enable the draggable.

  • option

    • .draggable( "option" , optionName , [value] )

      version added: 1.0

    Get or set any draggable option. If no value is specified, will act as a getter.

  • option

    • .draggable( "option" , options )

      version added: 1.0

    Set multiple draggable options at once by providing an options object.

  • widget

    • .draggable( "widget" )

      version added: 1.0

    Returns the .ui-draggable element.