Sortable Widget

Categories: Interactions

Sortable Widgetversion added: 1.0

Description: Reorder elements in a list or grid using the mouse.

QuickNavExamples

Options

Methods

Events

The jQuery UI Sortable plugin makes selected elements sortable by dragging with the mouse.

Options

appendTo 

Type: jQuery or Element or Selector or String
Default: "parent"
Defines where the helper that moves with the mouse is being appended to during the drag (for example, to resolve overlap/zIndex issues).
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.

axis 

Type: String
Default: false
If defined, the items can be dragged only horizontally or vertically. Possible values: "x", "y".

cancel 

Type: Selector
Default: ":input,button"
Prevents sorting if you start on elements matching the selector.

connectWith 

Type: Selector
Default: false
A selector of other sortable elements that the items from this list should be connected to. This is a one-way relationship, if you want the items to be connected in both directions, the connectWith option must be set on both sortable elements.

containment 

Type: Element or Selector or String
Default: false

Defines a bounding box that the sortable items are contrained 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".

cursor 

Type: String
Default: "auto"
Defines the cursor that is being shown while sorting.

cursorAt 

Type: Object
Default: false
Moves the sorting element or helper so the cursor always appears to drag from the same position. Coordinates can be given as a hash using a combination of one or two keys: { top, left, right, bottom }.

delay 

Type: Integer
Default: 0
Time in milliseconds to define when the sorting should start. Adding a delay helps preventing unwanted drags when clicking on an element.

disabled 

Type: Boolean
Default: false
Disables the sortable if set to true.

distance 

Type: Number
Default: 1
Tolerance, in pixels, for when sorting should start. If specified, sorting will not start until after mouse is dragged beyond distance. Can be used to allow for clicks on elements within a handle.

dropOnEmpty 

Type: Boolean
Default: true
If false, items from this sortable can't be dropped on an empty connect sortable (see the connectWith option.

forceHelperSize 

Type: Boolean
Default: false
If true, forces the helper to have a size.

forcePlaceholderSize 

Type: Boolean
Default: false
If true, forces the placeholder to have a size.

grid 

Type: Array
Default: false
Snaps the sorting element or helper to a grid, every x and y pixels. Array values: [ x, y ].

handle 

Type: Selector or Element
Default: false
Restricts sort start click to the specified element.

helper 

Type: String or Function()
Default: "original"
Allows for a helper element to be used for dragging display.
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.

items 

Type: Selector
Default: "> *"
Specifies which items inside the element should be sortable.

opacity 

Type: Number
Default: false
Defines the opacity of the helper while sorting. From 0.01 to 1.

placeholder 

Type: String
Default: false
A class name that gets applied to the otherwise white space.

revert 

Type: Boolean or Number
Default: false
Whether the sortable items should revert to their new positions using a smooth animation.
Multiple types supported:
  • Boolean: When set to true, the items will animate with the default duration.
  • Number: The duration for the animation, in milliseconds.

scroll 

Type: Boolean
Default: true
If set to true, the page scrolls when coming to an edge.

scrollSensitivity 

Type: Number
Default: 20
Defines how near the mouse must be to an edge to start scrolling.

scrollSpeed 

Type: Number
Default: 20
The speed at which the window should scroll once the mouse pointer gets within the scrollSensitivity distance.

tolerance 

Type: String
Default: "intersect"
Specifies which mode to use for testing whether the item being moved is hovering over another item. Possible values:
  • "intersect": The item overlaps the other item by at least 50%.
  • "pointer": The mouse pointer overlaps the other item.

zIndex 

Type: Integer
Default: 1000
Z-index for element/helper while being sorted.

Methods

cancel()Returns: jQuery (plugin only)

Cancels a change in the current sortable and reverts it to the state prior to when the current sort was started. Useful in the stop and receive callback functions.
  • This method does not accept any arguments.
Code examples:

Invoke the cancel method:

1
 
$( ".selector" ).sortable( "cancel" );

destroy()Returns: jQuery (plugin only)

Removes the sortable functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).sortable( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the sortable.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).sortable( "disable" );

enable()Returns: jQuery (plugin only)

Enables the sortable.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).sortable( "enable" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
$( ".selector" ).sortable( "option" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current sortable options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
$( ".selector" ).sortable( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the sortable option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).sortable( "option" );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the sortable.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).sortable( "option" );

refresh()Returns: jQuery (plugin only)

Refresh the sortable items. Triggers the reloading of all sortable items, causing new items to be recognized.
  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

1
 
$( ".selector" ).sortable( "refresh" );

refreshPositions()Returns: jQuery (plugin only)

Refresh the cached positions of the sortable items. Calling this method refreshes the cached item positions of all sortables.
  • This method does not accept any arguments.
Code examples:

Invoke the refreshPositions method:

1
 
$( ".selector" ).sortable( "refreshPositions" );

serialize( options )Returns: jQuery (plugin only)

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

  • options
    Type: Object
    Options to customize the serialization.
    • key
      Type: String
      Replaces part1[] with the specified value.
    • attribute
      Type: String
      The name of the attribute to use for the values.
    • expression
      Type: RegExp
      A regular expression used to split the attribute value into key and value parts.
Code examples:

Invoke the serialize method:

1
 
$( ".selector" ).sortable( "serialize" );

toArray()Returns: jQuery (plugin only)

Serializes the sortable's item id's into an array of string.
  • This method does not accept any arguments.
Code examples:

Invoke the toArray method:

1
 
$( ".selector" ).sortable( "toArray" );

widget()Returns: jQuery

Returns a jQuery object containing the sortable element.
  • This method does not accept any arguments.
Code examples:

Invoke the widget method:

1
 
$( ".selector" ).sortable( "widget" );

Events

activate( event, ui )Type: sortableactivate

This event is triggered when using connected lists, every connected list on drag start receives it.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the activate callback specified:

1
2
3
 
$( ".selector" ).sortable({
  activate: function( event, ui ) {}
});

Bind an event listener to the sortableactivate event:

1
 
$( ".selector" ).on( "sortableactivate", function( event, ui ) {} );

beforeStop( event, ui )Type: sortablebeforestop

This event is triggered when sorting stops, but when the placeholder/helper is still available.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the beforeStop callback specified:

1
2
3
 
$( ".selector" ).sortable({
  beforeStop: function( event, ui ) {}
});

Bind an event listener to the sortablebeforestop event:

1
 
$( ".selector" ).on( "sortablebeforestop", function( event, ui ) {} );

change( event, ui )Type: sortablechange

This event is triggered during sorting, but only when the DOM position has changed.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the change callback specified:

1
2
3
 
$( ".selector" ).sortable({
  change: function( event, ui ) {}
});

Bind an event listener to the sortablechange event:

1
 
$( ".selector" ).on( "sortablechange", function( event, ui ) {} );

create( event, ui )Type: sortablecreate

Triggered when the sortable is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the sortable with the create callback specified:

1
2
3
 
$( ".selector" ).sortable({
  create: function( event, ui ) {}
});

Bind an event listener to the sortablecreate event:

1
 
$( ".selector" ).on( "sortablecreate", function( event, ui ) {} );

deactivate( event, ui )Type: sortabledeactivate

This event is triggered when sorting was stopped, is propagated to all possible connected lists.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the deactivate callback specified:

1
2
3
 
$( ".selector" ).sortable({
  deactivate: function( event, ui ) {}
});

Bind an event listener to the sortabledeactivate event:

1
 
$( ".selector" ).on( "sortabledeactivate", function( event, ui ) {} );

out( event, ui )Type: sortableout

This event is triggered when a sortable item is moved away from a connected list.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the out callback specified:

1
2
3
 
$( ".selector" ).sortable({
  out: function( event, ui ) {}
});

Bind an event listener to the sortableout event:

1
 
$( ".selector" ).on( "sortableout", function( event, ui ) {} );

over( event, ui )Type: sortableover

This event is triggered when a sortable item is moved into a connected list.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the over callback specified:

1
2
3
 
$( ".selector" ).sortable({
  over: function( event, ui ) {}
});

Bind an event listener to the sortableover event:

1
 
$( ".selector" ).on( "sortableover", function( event, ui ) {} );

receive( event, ui )Type: sortablereceive

This event is triggered when an item from a connected sortable list has been dropped into another list. The latter is the event target.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the receive callback specified:

1
2
3
 
$( ".selector" ).sortable({
  receive: function( event, ui ) {}
});

Bind an event listener to the sortablereceive event:

1
 
$( ".selector" ).on( "sortablereceive", function( event, ui ) {} );

remove( event, ui )Type: sortableremove

This event is triggered when a sortable item from the list has been dropped into another. The former is the event target.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the remove callback specified:

1
2
3
 
$( ".selector" ).sortable({
  remove: function( event, ui ) {}
});

Bind an event listener to the sortableremove event:

1
 
$( ".selector" ).on( "sortableremove", function( event, ui ) {} );

sort( event, ui )Type: sortablesort

This event is triggered during sorting.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the sort callback specified:

1
2
3
 
$( ".selector" ).sortable({
  sort: function( event, ui ) {}
});

Bind an event listener to the sortablesort event:

1
 
$( ".selector" ).on( "sortablesort", function( event, ui ) {} );

start( event, ui )Type: sortablestart

This event is triggered when sorting starts.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the start callback specified:

1
2
3
 
$( ".selector" ).sortable({
  start: function( event, ui ) {}
});

Bind an event listener to the sortablestart event:

1
 
$( ".selector" ).on( "sortablestart", function( event, ui ) {} );

stop( event, ui )Type: sortablestop

This event is triggered when sorting has stopped.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the stop callback specified:

1
2
3
 
$( ".selector" ).sortable({
  stop: function( event, ui ) {}
});

Bind an event listener to the sortablestop event:

1
 
$( ".selector" ).on( "sortablestop", function( event, ui ) {} );

update( event, ui )Type: sortableupdate

This event is triggered when the user stopped sorting and the DOM position has changed.
  • event
    Type: Event
  • ui
    Type: Object
    • helper
      Type: jQuery
      The jQuery object representing the helper being sorted
    • item
      Type: jQuery
      The jQuery object representing the current dragged element
    • offset
      Type: Object
      The current absolute position of the helper represented as { top, left }
    • position
      Type: Object
      The current position of the helper represented as { top, left }
    • originalPosition
      Type: Object
      The original position of the element represented as { top, left }
    • sender
      Type: jQuery
      The sortable that the item comes from if moving from one sortable to another
Code examples:

Initialize the sortable with the update callback specified:

1
2
3
 
$( ".selector" ).sortable({
  update: function( event, ui ) {}
});

Bind an event listener to the sortableupdate event:

1
 
$( ".selector" ).on( "sortableupdate", function( event, ui ) {} );

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
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>sortable demo</title>
  <link rel="stylesheet" href="./code.jquery.com/ui/1.8.24/themes/base/jquery-ui.css">
  <script src="./code.jquery.com/jquery-1.8.2.js"></script>
  <script src="./code.jquery.com/ui/1.8.24/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>

Demo: