Sortable Widgetversion added: 1.0
Description: Reorder elements in a list or grid using the mouse.
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
Options
appendToType: jQuery or Element or Selector or String
"parent"
- 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.
Initialize the sortable with the appendTo option specified:
|
1
|
|
Get or set the appendTo option, after initialization:
|
1
2
3
4
5
|
|
axisType: String
false
"x", "y".Initialize the sortable with the axis option specified:
|
1
|
|
Get or set the axis option, after initialization:
|
1
2
3
4
5
|
|
cancelType: Selector
"input,textarea,button,select,option"
Initialize the sortable with the cancel option specified:
|
1
|
|
Get or set the cancel option, after initialization:
|
1
2
3
4
5
|
|
connectWithType: Selector
false
connectWith option must be set on both sortable elements.Initialize the sortable with the connectWith option specified:
|
1
|
|
Get or set the connectWith option, after initialization:
|
1
2
3
4
5
|
|
containmentType: Element or Selector or String
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.
- 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".
Initialize the sortable with the containment option specified:
|
1
|
|
Get or set the containment option, after initialization:
|
1
2
3
4
5
|
|
cursorType: String
"auto"
Initialize the sortable with the cursor option specified:
|
1
|
|
Get or set the cursor option, after initialization:
|
1
2
3
4
5
|
|
cursorAtType: Object
false
{ top, left, right, bottom }.Initialize the sortable with the cursorAt option specified:
|
1
|
|
Get or set the cursorAt option, after initialization:
|
1
2
3
4
5
|
|
delayType: Integer
0
Initialize the sortable with the delay option specified:
|
1
|
|
Get or set the delay option, after initialization:
|
1
2
3
4
5
|
|
disabledType: Boolean
false
true.Initialize the sortable with the disabled option specified:
|
1
|
|
Get or set the disabled option, after initialization:
|
1
2
3
4
5
|
|
distanceType: Number
1
Initialize the sortable with the distance option specified:
|
1
|
|
Get or set the distance option, after initialization:
|
1
2
3
4
5
|
|
dropOnEmptyType: Boolean
true
false, items from this sortable can't be dropped on an empty connect sortable (see the connectWith option.Initialize the sortable with the dropOnEmpty option specified:
|
1
|
|
Get or set the dropOnEmpty option, after initialization:
|
1
2
3
4
5
|
|
forceHelperSizeType: Boolean
false
true, forces the helper to have a size.Initialize the sortable with the forceHelperSize option specified:
|
1
|
|
Get or set the forceHelperSize option, after initialization:
|
1
2
3
4
5
|
|
forcePlaceholderSizeType: Boolean
false
Initialize the sortable with the forcePlaceholderSize option specified:
|
1
|
|
Get or set the forcePlaceholderSize option, after initialization:
|
1
2
3
4
5
|
|
gridType: Array
false
[ x, y ].Initialize the sortable with the grid option specified:
|
1
|
|
Get or set the grid option, after initialization:
|
1
2
3
4
5
|
|
handleType: Selector or Element
false
Initialize the sortable with the handle option specified:
|
1
|
|
Get or set the handle option, after initialization:
|
1
2
3
4
5
|
|
helperType: String or Function()
"original"
-
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.
Initialize the sortable with the helper option specified:
|
1
|
|
Get or set the helper option, after initialization:
|
1
2
3
4
5
|
|
itemsType: Selector
"> *"
Initialize the sortable with the items option specified:
|
1
|
|
Get or set the items option, after initialization:
|
1
2
3
4
5
|
|
opacityType: Number
false
0.01 to 1.Initialize the sortable with the opacity option specified:
|
1
|
|
Get or set the opacity option, after initialization:
|
1
2
3
4
5
|
|
placeholderType: String
false
Initialize the sortable with the placeholder option specified:
|
1
|
|
Get or set the placeholder option, after initialization:
|
1
2
3
4
5
|
|
revertType: Boolean or Number
false
-
Boolean: When set to
true, the items will animate with the default duration. - Number: The duration for the animation, in milliseconds.
Initialize the sortable with the revert option specified:
|
1
|
|
Get or set the revert option, after initialization:
|
1
2
3
4
5
|
|
scrollType: Boolean
true
Initialize the sortable with the scroll option specified:
|
1
|
|
Get or set the scroll option, after initialization:
|
1
2
3
4
5
|
|
scrollSensitivityType: Number
20
Initialize the sortable with the scrollSensitivity option specified:
|
1
|
|
Get or set the scrollSensitivity option, after initialization:
|
1
2
3
4
5
|
|
scrollSpeedType: Number
20
scrollSensitivity distance.Initialize the sortable with the scrollSpeed option specified:
|
1
|
|
Get or set the scrollSpeed option, after initialization:
|
1
2
3
4
5
|
|
toleranceType: String
"intersect"
-
"intersect": The item overlaps the other item by at least 50%. -
"pointer": The mouse pointer overlaps the other item.
Initialize the sortable with the tolerance option specified:
|
1
|
|
Get or set the tolerance option, after initialization:
|
1
2
3
4
5
|
|
zIndexType: Integer
1000
Initialize the sortable with the zIndex option specified:
|
1
|
|
Get or set the zIndex option, after initialization:
|
1
2
3
4
5
|
|
Methods
cancel()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the cancel method:
|
1
|
|
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
|
1
|
|
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
|
1
|
|
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
|
1
|
|
option( optionName )Returns: Object
optionName.-
optionNameType: StringThe name of the option to get.
Invoke the method:
|
1
|
|
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
|
1
|
|
option( optionName, value )Returns: jQuery (plugin only)
optionName.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
|
1
|
|
option( options )Returns: jQuery (plugin only)
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
|
1
|
|
refresh()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the refresh method:
|
1
|
|
refreshPositions()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the refreshPositions method:
|
1
|
|
serialize( options )Returns: String
Serializes the sortable's item ids 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:
|
1
|
|
toArray( options )Returns: Array
-
optionsType: ObjectOptions to customize the serialization.
-
attribute (default:
"id")Type: StringThe name of the attribute to use for the values.
-
Invoke the toArray method:
|
1
|
|
widget()Returns: jQuery
jQuery object containing the sortable element.
- This method does not accept any arguments.
Invoke the widget method:
|
1
|
|
Events
activate( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortactivate event:
|
1
|
|
beforeStop( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortbeforestop event:
|
1
|
|
change( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortchange event:
|
1
|
|
create( event, ui )Type: sortcreate
Note: The ui object is empty but included for consistency with other events.
Initialize the sortable with the create callback specified:
|
1
2
3
|
|
Bind an event listener to the sortcreate event:
|
1
|
|
deactivate( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortdeactivate event:
|
1
|
|
out( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortout event:
|
1
|
|
over( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortover event:
|
1
|
|
receive( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortreceive event:
|
1
|
|
remove( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortremove event:
|
1
|
|
sort( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sort event:
|
1
|
|
start( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortstart event:
|
1
|
|
stop( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortstop event:
|
1
|
|
update( event, ui )Type: 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:
|
1
2
3
|
|
Bind an event listener to the sortupdate event:
|
1
|
|
Example:
A simple jQuery UI Sortable.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
|