jQuery & jQuery UI Documentation

jQuery & jQuery UI

previous page next page

Draggable

jQuery UI Draggable

Overview

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.

Dependencies

  • UI Core
  • UI Widget
  • UI Mouse

Example

Initialize a draggable with default options.

$("#draggable").draggable();


<!DOCTYPE html>
<html>
<head>
  <link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/base/jquery-ui.css" rel="stylesheet" type="text/css"/>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5/jquery.min.js"></script>
  <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
  <style type="text/css">
    #draggable { width: 100px; height: 70px; background: silver; }
  </style>
  <script>
  $(document).ready(function() {
    $("#draggable").draggable();
  });
  </script>
</head>
<body style="font-size:62.5%;">
  
<div id="draggable">Drag me</div>

</body>
</html>

Options

  • disabled

    Type:
    Boolean
    Default:
    false

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

    Code examples

    Initialize a draggable with the disabled option specified. 
    $( ".selector" ).draggable({ disabled: true });
    Get or set the disabled option, after init. 
    //getter
var disabled = $( ".selector" ).draggable( "option", "disabled" );
//setter
$( ".selector" ).draggable( "option", "disabled", true );

  • 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() init on many hundreds of elements.

    Code examples

    Initialize a draggable with the addClasses option specified. 
    $( ".selector" ).draggable({ addClasses: false });
    Get or set the addClasses option, after init. 
    //getter
var addClasses = $( ".selector" ).draggable( "option", "addClasses" );
//setter
$( ".selector" ).draggable( "option", "addClasses", false );

  • appendTo

    Type:
    Element, Selector
    Default:
    'parent'

    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.

    Code examples

    Initialize a draggable with the appendTo option specified. 
    $( ".selector" ).draggable({ appendTo: 'body' });
    Get or set the appendTo option, after init. 
    //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 a draggable with the axis option specified. 
    $( ".selector" ).draggable({ axis: 'x' });
    Get or set the axis option, after init. 
    //getter
var axis = $( ".selector" ).draggable( "option", "axis" );
//setter
$( ".selector" ).draggable( "option", "axis", 'x' );

  • cancel

    Type:
    Selector
    Default:
    ':input,option'

    Prevents dragging from starting on specified elements.

    Code examples

    Initialize a draggable with the cancel option specified. 
    $( ".selector" ).draggable({ cancel: 'button' });
    Get or set the cancel option, after init. 
    //getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );
//setter
$( ".selector" ).draggable( "option", "cancel", 'button' );

  • connectToSortable

    Type:
    Selector
    Default:
    false

    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.

    Code examples

    Initialize a draggable with the connectToSortable option specified. 
    $( ".selector" ).draggable({ connectToSortable: 'ul#myList' });
    Get or set the connectToSortable option, after init. 
    //getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );
//setter
$( ".selector" ).draggable( "option", "connectToSortable", 'ul#myList' );

  • containment

    Type:
    Selector, Element, String, Array
    Default:
    false

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

    Code examples

    Initialize a draggable with the containment option specified. 
    $( ".selector" ).draggable({ containment: 'parent' });
    Get or set the containment option, after init. 
    //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 a draggable with the cursor option specified. 
    $( ".selector" ).draggable({ cursor: 'crosshair' });
    Get or set the cursor option, after init. 
    //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 a draggable with the cursorAt option specified. 
    $( ".selector" ).draggable({ cursorAt: { left: 5 } });
    Get or set the cursorAt option, after init. 
    //getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );
//setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );

  • delay

    Type:
    Integer
    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 a draggable with the delay option specified. 
    $( ".selector" ).draggable({ delay: 500 });
    Get or set the delay option, after init. 
    //getter
var delay = $( ".selector" ).draggable( "option", "delay" );
//setter
$( ".selector" ).draggable( "option", "delay", 500 );

  • distance

    Type:
    Integer
    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 a draggable with the distance option specified. 
    $( ".selector" ).draggable({ distance: 30 });
    Get or set the distance option, after init. 
    //getter
var distance = $( ".selector" ).draggable( "option", "distance" );
//setter
$( ".selector" ).draggable( "option", "distance", 30 );

  • grid

    Type:
    Array
    Default:
    false

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

    Code examples

    Initialize a draggable with the grid option specified. 
    $( ".selector" ).draggable({ grid: [50, 20] });
    Get or set the grid option, after init. 
    //getter
var grid = $( ".selector" ).draggable( "option", "grid" );
//setter
$( ".selector" ).draggable( "option", "grid", [50, 20] );

  • handle

    Type:
    Element, Selector
    Default:
    false

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

    Code examples

    Initialize a draggable with the handle option specified. 
    $( ".selector" ).draggable({ handle: 'h2' });
    Get or set the handle option, after init. 
    //getter
var handle = $( ".selector" ).draggable( "option", "handle" );
//setter
$( ".selector" ).draggable( "option", "handle", 'h2' );

  • helper

    Type:
    String, Function
    Default:
    'original'

    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.

    Code examples

    Initialize a draggable with the helper option specified. 
    $( ".selector" ).draggable({ helper: 'clone' });
    Get or set the helper option, after init. 
    //getter
var helper = $( ".selector" ).draggable( "option", "helper" );
//setter
$( ".selector" ).draggable( "option", "helper", 'clone' );

  • iframeFix

    Type:
    Boolean, Selector
    Default:
    false

    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.

    Code examples

    Initialize a draggable with the iframeFix option specified. 
    $( ".selector" ).draggable({ iframeFix: true });
    Get or set the iframeFix option, after init. 
    //getter
var iframeFix = $( ".selector" ).draggable( "option", "iframeFix" );
//setter
$( ".selector" ).draggable( "option", "iframeFix", true );

  • opacity

    Type:
    Float
    Default:
    false

    Opacity for the helper while being dragged.

    Code examples

    Initialize a draggable with the opacity option specified. 
    $( ".selector" ).draggable({ opacity: 0.35 });
    Get or set the opacity option, after init. 
    //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 a draggable with the refreshPositions option specified. 
    $( ".selector" ).draggable({ refreshPositions: true });
    Get or set the refreshPositions option, after init. 
    //getter
var refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" );
//setter
$( ".selector" ).draggable( "option", "refreshPositions", true );

  • revert

    Type:
    Boolean, String
    Default:
    false

    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.

    Code examples

    Initialize a draggable with the revert option specified. 
    $( ".selector" ).draggable({ revert: true });
    Get or set the revert option, after init. 
    //getter
var revert = $( ".selector" ).draggable( "option", "revert" );
//setter
$( ".selector" ).draggable( "option", "revert", true );

  • revertDuration

    Type:
    Integer
    Default:
    500

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

    Code examples

    Initialize a draggable with the revertDuration option specified. 
    $( ".selector" ).draggable({ revertDuration: 1000 });
    Get or set the revertDuration option, after init. 
    //getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );
//setter
$( ".selector" ).draggable( "option", "revertDuration", 1000 );

  • 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 a draggable with the scope option specified. 
    $( ".selector" ).draggable({ scope: 'tasks' });
    Get or set the scope option, after init. 
    //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 a draggable with the scroll option specified. 
    $( ".selector" ).draggable({ scroll: false });
    Get or set the scroll option, after init. 
    //getter
var scroll = $( ".selector" ).draggable( "option", "scroll" );
//setter
$( ".selector" ).draggable( "option", "scroll", false );

  • scrollSensitivity

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

    Code examples

    Initialize a draggable with the scrollSensitivity option specified. 
    $( ".selector" ).draggable({ scrollSensitivity: 40 });
    Get or set the scrollSensitivity option, after init. 
    //getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );
//setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 40 );

  • scrollSpeed

    Type:
    Integer
    Default:
    20

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

    Code examples

    Initialize a draggable with the scrollSpeed option specified. 
    $( ".selector" ).draggable({ scrollSpeed: 40 });
    Get or set the scrollSpeed option, after init. 
    //getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );
//setter
$( ".selector" ).draggable( "option", "scrollSpeed", 40 );

  • snap

    Type:
    Boolean, Selector
    Default:
    false

    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.

    Code examples

    Initialize a draggable with the snap option specified. 
    $( ".selector" ).draggable({ snap: true });
    Get or set the snap option, after init. 
    //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 snap is false. Possible values: 'inner', 'outer', 'both'

    Code examples

    Initialize a draggable with the snapMode option specified. 
    $( ".selector" ).draggable({ snapMode: 'outer' });
    Get or set the snapMode option, after init. 
    //getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );
//setter
$( ".selector" ).draggable( "option", "snapMode", 'outer' );

  • snapTolerance

    Type:
    Integer
    Default:
    20

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

    Code examples

    Initialize a draggable with the snapTolerance option specified. 
    $( ".selector" ).draggable({ snapTolerance: 40 });
    Get or set the snapTolerance option, after init. 
    //getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );
//setter
$( ".selector" ).draggable( "option", "snapTolerance", 40 );

  • stack

    Type:
    Selector
    Default:
    false

    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.

    Code examples

    Initialize a draggable with the stack option specified. 
    $( ".selector" ).draggable({ stack: ".products" });
    Get or set the stack option, after init. 
    //getter
var stack = $( ".selector" ).draggable( "option", "stack" );
//setter
$( ".selector" ).draggable( "option", "stack", ".products" );

  • zIndex

    Type:
    Integer
    Default:
    false

    z-index for the helper while being dragged.

    Code examples

    Initialize a draggable with the zIndex option specified. 
    $( ".selector" ).draggable({ zIndex: 2700 });
    Get or set the zIndex option, after init. 
    //getter
var zIndex = $( ".selector" ).draggable( "option", "zIndex" );
//setter
$( ".selector" ).draggable( "option", "zIndex", 2700 );

Events

  • create

    Type:
    dragcreate

    This event is triggered when draggable is created.

    Code examples

    Supply a callback function to handle the create event as an init option. 
    $( ".selector" ).draggable({
   create: function(event, ui) { ... }
});
    Bind to the create event by type: dragcreate. 
    $( ".selector" ).bind( "dragcreate", function(event, ui) {
  ...
});

  • start

    Type:
    dragstart

    This event is triggered when dragging starts.

    Code examples

    Supply a callback function to handle the start event as an init option. 
    $( ".selector" ).draggable({
   start: function(event, ui) { ... }
});
    Bind to the start event by type: dragstart. 
    $( ".selector" ).bind( "dragstart", function(event, ui) {
  ...
});

  • drag

    Type:
    drag

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

    Code examples

    Supply a callback function to handle the drag event as an init option. 
    $( ".selector" ).draggable({
   drag: function(event, ui) { ... }
});
    Bind to the drag event by type: drag. 
    $( ".selector" ).bind( "drag", function(event, ui) {
  ...
});

  • stop

    Type:
    dragstop

    This event is triggered when dragging stops.

    Code examples

    Supply a callback function to handle the stop event as an init option. 
    $( ".selector" ).draggable({
   stop: function(event, ui) { ... }
});
    Bind to the stop event by type: dragstop. 
    $( ".selector" ).bind( "dragstop", function(event, ui) {
  ...
});

Methods

  • destroy

    Signature:
    .draggable( "destroy" )

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

  • disable

    Signature:
    .draggable( "disable" )

    Disable the draggable.

  • enable

    Signature:
    .draggable( "enable" )

    Enable the draggable.

  • option

    Signature:
    .draggable( "option" , optionName , [value] )

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

  • option

    Signature:
    .draggable( "option" , options )

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

  • widget

    Signature:
    .draggable( "widget" )

    Returns the .ui-draggable element.

Theming

The jQuery UI Draggable plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.

If a deeper level of customization is needed, there are widget-specific classes referenced within the jquery.ui.draggable.css stylesheet that can be modified. These classes are highlighed in bold below.

Sample markup with jQuery UI CSS Framework classes

<div class="ui-draggable"></div>

Note: This is a sample of markup generated by the draggable plugin, not markup you should use to create a draggable. The only markup needed for that is <div></div>.

previous page start next page