Sortable Widget version 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,button"
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()
-
This method does not accept any arguments.
Invoke the cancel method:
1
|
|
destroy()
-
This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()
-
This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()
-
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 method does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
refresh()
-
This method does not accept any arguments.
Invoke the refresh method:
1
|
|
refreshPositions()
-
This method does not accept any arguments.
Invoke the refreshPositions method:
1
|
|
serialize( options )Returns: String
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:
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
-
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
-
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
-
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
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
-
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 connected 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
-
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
-
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
-
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 }
-
senderType: jQueryThe sortable that the item comes from if moving from one sortable to another
-
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
-
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
-
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
-
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
-
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
|
|