The jQuery UI Sortable plugin makes selected elements sortable by dragging with the mouse.
Note: In order to sort table rows, the tbody
must be made sortable, not the table
.
Dependencies
- UI Core
- Widget Factory
- Mouse Interaction
"parent"
Multiple types supported:
- jQuery: A jQuery object containing the element to append the helper to.
- Element: The element to append the helper to.
- Selector: A selector specifying which element to append the helper to.
- String: The string
"parent"
will cause the helper to be a sibling of the sortable item.
Code examples:
Initialize the sortable with the appendTo
option specified:
$( ".selector" ).sortable({ appendTo: document.body });
Get or set the appendTo
option, after initialization:
// Getter var appendTo = $( ".selector" ).sortable( "option", "appendTo" ); // Setter $( ".selector" ).sortable( "option", "appendTo", document.body );
false
"x"
, "y"
.Code examples:
Initialize the sortable with the axis
option specified:
$( ".selector" ).sortable({ axis: "x" });
Get or set the axis
option, after initialization:
// Getter var axis = $( ".selector" ).sortable( "option", "axis" ); // Setter $( ".selector" ).sortable( "option", "axis", "x" );
"input,textarea,button,select,option"
Code examples:
Initialize the sortable with the cancel
option specified:
$( ".selector" ).sortable({ cancel: "a,button" });
Get or set the cancel
option, after initialization:
// Getter var cancel = $( ".selector" ).sortable( "option", "cancel" ); // Setter $( ".selector" ).sortable( "option", "cancel", "a,button" );
false
connectWith
option must be set on both sortable elements.Code examples:
Initialize the sortable with the connectWith
option specified:
$( ".selector" ).sortable({ connectWith: "#shopping-cart" });
Get or set the connectWith
option, after initialization:
// Getter var connectWith = $( ".selector" ).sortable( "option", "connectWith" ); // Setter $( ".selector" ).sortable( "option", "connectWith", "#shopping-cart" );
false
Defines a bounding box that the sortable items are constrained to while dragging.
Note: The element specified for containment must have a calculated width and height (though it need not be explicit). For example, if you have float: left
sortable children and specify containment: "parent"
be sure to have float: left
on the sortable/parent container as well or it will have height: 0
, causing undefined behavior.
Multiple types supported:
- Element: An element to use as the container.
- Selector: A selector specifying an element to use as the container.
- String: A string identifying an element to use as the container. Possible values:
"parent"
,"document"
,"window"
.
Code examples:
Initialize the sortable with the containment
option specified:
$( ".selector" ).sortable({ containment: "parent" });
Get or set the containment
option, after initialization:
// Getter var containment = $( ".selector" ).sortable( "option", "containment" ); // Setter $( ".selector" ).sortable( "option", "containment", "parent" );
"auto"
Code examples:
Initialize the sortable with the cursor
option specified:
$( ".selector" ).sortable({ cursor: "move" });
Get or set the cursor
option, after initialization:
// Getter var cursor = $( ".selector" ).sortable( "option", "cursor" ); // Setter $( ".selector" ).sortable( "option", "cursor", "move" );
false
{ top, left, right, bottom }
.Code examples:
Initialize the sortable with the cursorAt
option specified:
$( ".selector" ).sortable({ cursorAt: { left: 5 } });
Get or set the cursorAt
option, after initialization:
// Getter var cursorAt = $( ".selector" ).sortable( "option", "cursorAt" ); // Setter $( ".selector" ).sortable( "option", "cursorAt", { left: 5 } );
0
Code examples:
Initialize the sortable with the delay
option specified:
$( ".selector" ).sortable({ delay: 150 });
Get or set the delay
option, after initialization:
// Getter var delay = $( ".selector" ).sortable( "option", "delay" ); // Setter $( ".selector" ).sortable( "option", "delay", 150 );
false
true
.Code examples:
Initialize the sortable with the disabled
option specified:
$( ".selector" ).sortable({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).sortable( "option", "disabled" ); // Setter $( ".selector" ).sortable( "option", "disabled", true );
1
Code examples:
Initialize the sortable with the distance
option specified:
$( ".selector" ).sortable({ distance: 5 });
Get or set the distance
option, after initialization:
// Getter var distance = $( ".selector" ).sortable( "option", "distance" ); // Setter $( ".selector" ).sortable( "option", "distance", 5 );
true
false
, items from this sortable can't be dropped on an empty connect sortable (see the connectWith
option.Code examples:
Initialize the sortable with the dropOnEmpty
option specified:
$( ".selector" ).sortable({ dropOnEmpty: false });
Get or set the dropOnEmpty
option, after initialization:
// Getter var dropOnEmpty = $( ".selector" ).sortable( "option", "dropOnEmpty" ); // Setter $( ".selector" ).sortable( "option", "dropOnEmpty", false );
false
true
, forces the helper to have a size.Code examples:
Initialize the sortable with the forceHelperSize
option specified:
$( ".selector" ).sortable({ forceHelperSize: true });
Get or set the forceHelperSize
option, after initialization:
// Getter var forceHelperSize = $( ".selector" ).sortable( "option", "forceHelperSize" ); // Setter $( ".selector" ).sortable( "option", "forceHelperSize", true );
false
Code examples:
Initialize the sortable with the forcePlaceholderSize
option specified:
$( ".selector" ).sortable({ forcePlaceholderSize: true });
Get or set the forcePlaceholderSize
option, after initialization:
// Getter var forcePlaceholderSize = $( ".selector" ).sortable( "option", "forcePlaceholderSize" ); // Setter $( ".selector" ).sortable( "option", "forcePlaceholderSize", true );
false
[ x, y ]
.Code examples:
Initialize the sortable with the grid
option specified:
$( ".selector" ).sortable({ grid: [ 20, 10 ] });
Get or set the grid
option, after initialization:
// Getter var grid = $( ".selector" ).sortable( "option", "grid" ); // Setter $( ".selector" ).sortable( "option", "grid", [ 20, 10 ] );
false
Code examples:
Initialize the sortable with the handle
option specified:
$( ".selector" ).sortable({ handle: ".handle" });
Get or set the handle
option, after initialization:
// Getter var handle = $( ".selector" ).sortable( "option", "handle" ); // Setter $( ".selector" ).sortable( "option", "handle", ".handle" );
"original"
Multiple types supported:
- String: If set to
"clone"
, then the element will be cloned and the clone will be dragged. - Function: A function that will return a DOMElement to use while dragging. The function receives the event and the element being sorted.
Code examples:
Initialize the sortable with the helper
option specified:
$( ".selector" ).sortable({ helper: "clone" });
Get or set the helper
option, after initialization:
// Getter var helper = $( ".selector" ).sortable( "option", "helper" ); // Setter $( ".selector" ).sortable( "option", "helper", "clone" );
"> *"
Code examples:
Initialize the sortable with the items
option specified:
$( ".selector" ).sortable({ items: "> li" });
Get or set the items
option, after initialization:
// Getter var items = $( ".selector" ).sortable( "option", "items" ); // Setter $( ".selector" ).sortable( "option", "items", "> li" );
false
0.01
to 1
.Code examples:
Initialize the sortable with the opacity
option specified:
$( ".selector" ).sortable({ opacity: 0.5 });
Get or set the opacity
option, after initialization:
// Getter var opacity = $( ".selector" ).sortable( "option", "opacity" ); // Setter $( ".selector" ).sortable( "option", "opacity", 0.5 );
false
Code examples:
Initialize the sortable with the placeholder
option specified:
$( ".selector" ).sortable({ placeholder: "sortable-placeholder" });
Get or set the placeholder
option, after initialization:
// Getter var placeholder = $( ".selector" ).sortable( "option", "placeholder" ); // Setter $( ".selector" ).sortable( "option", "placeholder", "sortable-placeholder" );
false
Multiple types supported:
- Boolean: When set to
true
, the items will animate with the default duration. - Number: The duration for the animation, in milliseconds.
Code examples:
Initialize the sortable with the revert
option specified:
$( ".selector" ).sortable({ revert: true });
Get or set the revert
option, after initialization:
// Getter var revert = $( ".selector" ).sortable( "option", "revert" ); // Setter $( ".selector" ).sortable( "option", "revert", true );
true
Code examples:
Initialize the sortable with the scroll
option specified:
$( ".selector" ).sortable({ scroll: false });
Get or set the scroll
option, after initialization:
// Getter var scroll = $( ".selector" ).sortable( "option", "scroll" ); // Setter $( ".selector" ).sortable( "option", "scroll", false );
20
Code examples:
Initialize the sortable with the scrollSensitivity
option specified:
$( ".selector" ).sortable({ scrollSensitivity: 10 });
Get or set the scrollSensitivity
option, after initialization:
// Getter var scrollSensitivity = $( ".selector" ).sortable( "option", "scrollSensitivity" ); // Setter $( ".selector" ).sortable( "option", "scrollSensitivity", 10 );
20
scrollSensitivity
distance.Code examples:
Initialize the sortable with the scrollSpeed
option specified:
$( ".selector" ).sortable({ scrollSpeed: 40 });
Get or set the scrollSpeed
option, after initialization:
// Getter var scrollSpeed = $( ".selector" ).sortable( "option", "scrollSpeed" ); // Setter $( ".selector" ).sortable( "option", "scrollSpeed", 40 );
"intersect"
-
"intersect"
: The item overlaps the other item by at least 50%. -
"pointer"
: The mouse pointer overlaps the other item.
Code examples:
Initialize the sortable with the tolerance
option specified:
$( ".selector" ).sortable({ tolerance: "pointer" });
Get or set the tolerance
option, after initialization:
// Getter var tolerance = $( ".selector" ).sortable( "option", "tolerance" ); // Setter $( ".selector" ).sortable( "option", "tolerance", "pointer" );
1000
Code examples:
Initialize the sortable with the zIndex
option specified:
$( ".selector" ).sortable({ zIndex: 9999 });
Get or set the zIndex
option, after initialization:
// Getter var zIndex = $( ".selector" ).sortable( "option", "zIndex" ); // Setter $( ".selector" ).sortable( "option", "zIndex", 9999 );
- This method does not accept any arguments.
Invoke the cancel method:
$( ".selector" ).sortable( "cancel" );
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).sortable( "destroy" );
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).sortable( "disable" );
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).sortable( "enable" );
Retrieves the sortable's instance object. If the element does not have an associated instance, undefined
is returned.
Unlike other widget methods, instance()
is safe to call on any element after the sortable plugin has loaded.
- This method does not accept any arguments.
Invoke the instance method:
$( ".selector" ).sortable( "instance" );
Gets the value currently associated with the specified optionName
.
Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar"
would get the value of the bar
property on the foo
option.
- optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).sortable( "option", "disabled" );
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).sortable( "option" );
Sets the value of the sortable option associated with the specified optionName
.
Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName
. For example, "foo.bar"
would update only the bar
property of the foo
option.
- optionNameType: StringThe name of the option to set.
- valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).sortable( "option", "disabled", true );
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).sortable( "option", { disabled: true } );
- This method does not accept any arguments.
Invoke the refresh method:
$( ".selector" ).sortable( "refresh" );
- This method does not accept any arguments.
Invoke the refreshPositions method:
$( ".selector" ).sortable( "refreshPositions" );
Serializes the sortable's item id
s into a form/ajax submittable string. Calling this method produces a hash that can be appended to any url to easily submit a new item order back to the server.
It works by default by looking at the id
of each item in the format "setname_number"
, and it spits out a hash like "setname[]=number&setname[]=number"
.
Note: If serialize returns an empty string, make sure the id
attributes include an underscore. They must be in the form: "set_number"
For example, a 3 element list with id
attributes "foo_1"
, "foo_5"
, "foo_2"
will serialize to "foo[]=1&foo[]=5&foo[]=2"
. You can use an underscore, equal sign or hyphen to separate the set and number. For example "foo=1"
, "foo-1"
, and "foo_1"
all serialize to "foo[]=1"
.
- optionsType: ObjectOptions to customize the serialization.
- key (default:
the part of the attribute in front of the separator
)Type: StringReplacespart1[]
with the specified value. - attribute (default:
"id"
)Type: StringThe name of the attribute to use for the values. - expression (default:
/(.+)[-=_](.+)/
)Type: RegExpA regular expression used to split the attribute value into key and value parts.
-
Invoke the serialize method:
var sorted = $( ".selector" ).sortable( "serialize", { key: "sort" } );
- optionsType: ObjectOptions to customize the serialization.
- attribute (default:
"id"
)Type: StringThe name of the attribute to use for the values.
-
Invoke the toArray method:
var sortedIDs = $( ".selector" ).sortable( "toArray" );
jQuery
object containing the sortable element. - This method does not accept any arguments.
Invoke the widget method:
var widget = $( ".selector" ).sortable( "widget" );
sortactivate
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the activate callback specified:
$( ".selector" ).sortable({ activate: function( event, ui ) {} });
Bind an event listener to the sortactivate event:
$( ".selector" ).on( "sortactivate", function( event, ui ) {} );
sortbeforestop
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the beforeStop callback specified:
$( ".selector" ).sortable({ beforeStop: function( event, ui ) {} });
Bind an event listener to the sortbeforestop event:
$( ".selector" ).on( "sortbeforestop", function( event, ui ) {} );
sortchange
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the change callback specified:
$( ".selector" ).sortable({ change: function( event, ui ) {} });
Bind an event listener to the sortchange event:
$( ".selector" ).on( "sortchange", function( event, ui ) {} );
sortcreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the sortable with the create callback specified:
$( ".selector" ).sortable({ create: function( event, ui ) {} });
Bind an event listener to the sortcreate event:
$( ".selector" ).on( "sortcreate", function( event, ui ) {} );
sortdeactivate
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the deactivate callback specified:
$( ".selector" ).sortable({ deactivate: function( event, ui ) {} });
Bind an event listener to the sortdeactivate event:
$( ".selector" ).on( "sortdeactivate", function( event, ui ) {} );
sortout
This event is triggered when a sortable item is moved away from a sortable list.
Note: This event is also triggered when a sortable item is dropped.
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the out callback specified:
$( ".selector" ).sortable({ out: function( event, ui ) {} });
Bind an event listener to the sortout event:
$( ".selector" ).on( "sortout", function( event, ui ) {} );
sortover
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the over callback specified:
$( ".selector" ).sortable({ over: function( event, ui ) {} });
Bind an event listener to the sortover event:
$( ".selector" ).on( "sortover", function( event, ui ) {} );
sortreceive
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the receive callback specified:
$( ".selector" ).sortable({ receive: function( event, ui ) {} });
Bind an event listener to the sortreceive event:
$( ".selector" ).on( "sortreceive", function( event, ui ) {} );
sortremove
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the remove callback specified:
$( ".selector" ).sortable({ remove: function( event, ui ) {} });
Bind an event listener to the sortremove event:
$( ".selector" ).on( "sortremove", function( event, ui ) {} );
sort
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the sort callback specified:
$( ".selector" ).sortable({ sort: function( event, ui ) {} });
Bind an event listener to the sort event:
$( ".selector" ).on( "sort", function( event, ui ) {} );
sortstart
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the start callback specified:
$( ".selector" ).sortable({ start: function( event, ui ) {} });
Bind an event listener to the sortstart event:
$( ".selector" ).on( "sortstart", function( event, ui ) {} );
sortstop
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the stop callback specified:
$( ".selector" ).sortable({ stop: function( event, ui ) {} });
Bind an event listener to the sortstop event:
$( ".selector" ).on( "sortstop", function( event, ui ) {} );
sortupdate
- eventType: Event
- uiType: Object
- helperType: jQueryThe jQuery object representing the helper being sorted.
- itemType: jQueryThe jQuery object representing the current dragged element.
- offsetType: ObjectThe current absolute position of the helper represented as
{ top, left }
. - positionType: ObjectThe current position of the helper represented as
{ top, left }
. - originalPositionType: ObjectThe original position of the element represented as
{ top, left }
. - senderType: jQueryThe sortable that the item comes from if moving from one sortable to another.
- placeholderType: jQueryThe jQuery object representing the element being used as a placeholder.
-
Initialize the sortable with the update callback specified:
$( ".selector" ).sortable({ update: function( event, ui ) {} });
Bind an event listener to the sortupdate event:
$( ".selector" ).on( "sortupdate", function( event, ui ) {} );
A simple jQuery UI Sortable.
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>sortable demo</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css"> <script src="//code.jquery.com/jquery-1.10.2.js"></script> <script src="//code.jquery.com/ui/1.11.4/jquery-ui.js"></script> </head> <body> <ul id="sortable"> <li>Item 1</li> <li>Item 2</li> <li>Item 3</li> <li>Item 4</li> <li>Item 5</li> </ul> <script>$("#sortable").sortable();</script> </body> </html>
Please login to continue.