QuickNav

Options

appendTo
axis
cancel
connectWith
containment
cursor
cursorAt
delay
disabled
distance
dropOnEmpty
forceHelperSize
forcePlaceholderSize
grid
handle
helper
items
opacity
placeholder
revert
scroll
scrollSensitivity
scrollSpeed
tolerance
zIndex

Methods

cancel
destroy
disable
enable
option
refresh
refreshPositions
serialize
toArray
widget

Events

create
start
sort
change
beforeStop
stop
update
receive
remove
over
out
activate
deactivate

Sortable Widgetversion added: 1.0

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

Options

appendToType: 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.

axisType: String

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

cancelType: Selector

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

connectWithType: 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.

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

cursorType: String

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

cursorAtType: 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 }.

delayType: 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.

disabledType: Boolean

Default: false
Disables the sortable if set to true.

distanceType: 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.

dropOnEmptyType: Boolean

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

forceHelperSizeType: Boolean

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

forcePlaceholderSizeType: Boolean

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

gridType: Array

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

handleType: Selector or Element

Default: false
Restricts sort start click to the specified element.

helperType: 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.

itemsType: Selector

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

opacityType: Number

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

placeholderType: String

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

revertType: 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.

scrollType: Boolean

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

scrollSensitivityType: Number

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

scrollSpeedType: Number

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

toleranceType: 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.

zIndexType: Integer

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

Methods

cancel()

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.

destroy()

Removes the sortable functionality completely. This will return the element back to its pre-init state.

disable()

Disables the sortable.

enable()

Enables the sortable.

option( optionName ) Returns: Object

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

option() Returns: PlainObject

Gets an object containing key/value pairs representing the current sortable options hash.

option( optionName, value )

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.

option( options )

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

refresh()

Refresh the sortable items. Triggers the reloading of all sortable items, causing new items to be recognized.

refreshPositions()

Refresh the cached positions of the sortable items. Calling this method refreshes the cached item positions of all sortables.

serialize( options )

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.

toArray()

Serializes the sortable's item id's into an array of string.

widget() Returns: jQuery

Returns a jQuery object containing the sortable element.

Events

activate( event, ui )

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

beforeStop( event, ui )

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

change( event, ui )

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

create( event, ui )

Triggered when the sortable is created.

deactivate( event, ui )

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

out( event, ui )

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

over( event, ui )

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

receive( event, ui )

This event is triggered when a connected sortable list has received an item from another 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

remove( event, ui )

This event is triggered when a sortable item has been dragged out from the list and into another.
  • 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

sort( event, ui )

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

start( event, ui )

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

stop( event, ui )

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

update( event, ui )

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

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

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="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css">
    <script src="http://code.jquery.com/jquery-1.8.2.js"></script>
    <script src="http://code.jquery.com/ui/1.9.0/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: