YouTip LogoYouTip

Home > jQuery UI > Api Sortable

Api Sortable

📅 2026-06-18 | 📂 jQuery UI

jQuery UI API – Sortable Widget

Category

Interactions

Usage

Description: Use the mouse to reorder elements within a list or grid.

Added in version: 1.0

Dependencies:

Note: The jQuery UI Sortable plugin allows selected elements to be sorted by dragging with the mouse.

Note: To sort table rows, the tbody must be sortable, not the table.

Quick Navigation

Options Methods Events
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 cancel destroy disable enable option refresh refreshPositions serialize toArray widget activate beforeStop change create deactivate out over receive remove sort start stop update
Option Type Description Default
appendTo jQuery or Element or Selector or String Where the helper being moved with the mouse is appended to (e.g., 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.
Code examples:
Initialize a sortable with the specified appendTo option: 
$( ".selector" ).sortable({ appendTo: document.body });
After initialization, get or set the appendTo option: 
// getter
var appendTo = $( ".selector" ).sortable( "option", "appendTo" );

// setter
$( ".selector" ).sortable( "option", "appendTo", document.body );
 "parent"
axis String If defined, the items can only be moved horizontally or vertically. Possible values: "x", "y".

Code examples:
Initialize a sortable with the specified axis option: 
$( ".selector" ).sortable({ axis: "x" });
After initialization, get or set the axis option: 
// getter
var axis = $( ".selector" ).sortable( "option", "axis" );

// setter
$( ".selector" ).sortable( "option", "axis", "x" );
 false
cancel Selector Prevents sorting from starting on elements matching the selector.

Code examples:
Initialize a sortable with the specified cancel option: 
$( ".selector" ).sortable({ cancel: "a,button" });
After initialization, get or set the cancel option: 
// getter
var cancel = $( ".selector" ).sortable( "option", "cancel" );

// setter
$( ".selector" ).sortable( "option", "cancel", "a,button" );
 "input, textarea, button, select, option"
connectWith Selector A selector of other sortable elements that the items in this list should be connected to. This is a one-way relationship. If you want items to be connected both ways, the connectWith option must be set on both sortable elements.

Code examples:
Initialize a sortable with the specified connectWith option: 
$( ".selector" ).sortable({ connectWith: "#shopping-cart" });
After initialization, get or set the connectWith option: 
// getter
var connectWith = $( ".selector" ).sortable( "option", "connectWith" );

// setter
$( ".selector" ).sortable( "option", "connectWith", "#shopping-cart" );
 false
containment Element or Selector or String Defines the boundaries that the sortable items are constrained to while dragging.

Note: The element specified for containment must have a calculated width and height (though it doesn't need to be explicit). For example, if you have float: left sortable children and specify containment: "parent", ensure the sortable/parent container also has float: left, otherwise it will have height: 0, leading to 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 a sortable with the specified containment option: 
$( ".selector" ).sortable({ containment: "parent" });
After initialization, get or set the containment option: 
// getter
var containment = $( ".selector" ).sortable( "option", "containment" );

// setter
$( ".selector" ).sortable( "option", "containment", "parent" );
 false
cursor String Defines the cursor that is shown when sorting.

Code examples:
Initialize a sortable with the specified cursor option: 
$( ".selector" ).sortable({ cursor: "move" });
After initialization, get or set the cursor option: 
// getter
var cursor = $( ".selector" ).sortable( "option", "cursor" );

// setter
$( ".selector" ).sortable( "option", "cursor", "move" );
 "auto"
cursorAt Object Moves the sorting element or helper so the cursor always appears to drag from the same position. Coordinates can be given as a hash with one or two keys: { top, left, right, bottom }.

Code examples:
Initialize a sortable with the specified cursorAt option: 
$( ".selector" ).sortable({ cursorAt: { left: 5 } });
After initialization, get or set the cursorAt option: 
// getter
var cursorAt = $( ".selector" ).sortable( "option", "cursorAt" );

// setter
$( ".selector" ).sortable( "option", "cursorAt", { left: 5 } );
 false
delay Integer Time in milliseconds after mousedown before sorting begins. This option can prevent unwanted drags when clicking on an element.

Code examples:
Initialize a sortable with the specified delay option: 
$( ".selector" ).sortable({ delay: 150 });
After initialization, get or set the delay option: 
// getter
var delay = $( ".selector" ).sortable( "option", "delay" );

// setter
$( ".selector" ).sortable( "option", "delay", 150 );
 0
disabled Boolean If set to true, disables the sortable.

Code examples:
Initialize a sortable with the specified disabled option: 
$( ".selector" ).sortable({ disabled: true });
After initialization, get or set the disabled option: 
// getter
var disabled = $( ".selector" ).sortable( "option", "disabled" );

// setter
$( ".selector" ).sortable( "option", "disabled", true );
 false
distance Number Distance in pixels that the mouse must move before sorting begins. If this option is specified, sorting will not begin until the mouse has moved beyond the specified distance. This option can be used to allow clicks on elements within a handle.

Code examples:
Initialize a sortable with the specified distance option: 
$( ".selector" ).sortable({ distance: 5 });
After initialization, get or set the distance option: 
// getter
var distance = $( ".selector" ).sortable( "option", "distance" );

// setter
$( ".selector" ).sortable( "option", "distance", 5 );
 1
dropOnEmpty Boolean If false, items from this sortable cannot be dropped on an empty connected sortable (see the connectWith option).

Code examples:
Initialize a sortable with the specified dropOnEmpty option: 
$( ".selector" ).sortable({ dropOnEmpty: false });
After initialization, get or set the dropOnEmpty option: 
// getter
var dropOnEmpty = $( ".selector" ).sortable( "option", "dropOnEmpty" );

// setter
$( ".selector" ).sortable( "option", "dropOnEmpty", false );
 true
forceHelperSize Boolean If true, forces the helper to have a size.

Code examples:
Initialize a sortable with the specified forceHelperSize option: 
$( ".selector" ).sortable({ forceHelperSize: true });
After initialization, get or set the forceHelperSize option: 
// getter
var forceHelperSize = $( ".selector" ).sortable( "option", "forceHelperSize" );

// setter
$( ".selector" ).sortable( "option", "forceHelperSize", true );
 false
forcePlaceholderSize Boolean If true, forces the placeholder to have a size.

Code examples:
Initialize a sortable with the specified forcePlaceholderSize option: 
$( ".selector" ).sortable({ forcePlaceholderSize: true });
After initialization, get or set the forcePlaceholderSize option: 
// getter
var forcePlaceholderSize = $( ".selector" ).sortable( "option", "forcePlaceholderSize" );

// setter
$( ".selector" ).sortable( "option", "forcePlaceholderSize", true );
 false
grid Array Snaps the sorting element or helper to a grid, every x and y pixel. The array form must be [ x, y ].

Code examples:
Initialize a sortable with the specified grid option: 
$( ".selector" ).sortable({ grid: [ 20, 10 ] });
After initialization, get or set the grid option: 
// getter
var grid = $( ".selector" ).sortable( "option", "grid" );

// setter
$( ".selector" ).sortable( "option", "grid", [ 20, 10 ] );
 false
handle Selector or Element If specified, restricts sorting from starting on elements other than the specified one(s).

Code examples:
Initialize a sortable with the specified handle option: 
$( ".selector" ).sortable({ handle: ".handle" });
After initialization, get or set the handle option: 
// getter
var handle = $( ".selector" ).sortable( "option", "handle" );

// setter
$( ".selector" ).sortable( "option", "handle", ".handle" );
 false
helper String or Function() Allows for a helper element to be used for dragging display.

Multiple types supported:
  • String: If set to "clone", the element will be cloned and the clone will be dragged.
  • Function: A function that will return a DOMElement to be used while dragging. The function receives the event, and the element being sorted.
Code examples:
Initialize a sortable with the specified helper option: 
$( ".selector" ).sortable({ helper: "clone" });
After initialization, get or set the helper option: 
// getter
var helper = $( ".selector" ).sortable( "option", "helper" );

// setter
$( ".selector" ).sortable( "option", "helper", "clone" );
 "original"
items Selector Specifies which items inside the element should be sortable.

Code examples:
Initialize a sortable with the specified items option: 
$( ".selector" ).sortable({ items: "> li" });
After initialization, get or set the items option: 
// getter
var items = $( ".selector" ).sortable( "option", "items" );

// setter
$( ".selector" ).sortable( "option", "items", "> li" );
 "> *"
opacity Number The opacity of the helper while sorting. From 0.01 to 1.

Code examples:
Initialize a sortable with the specified opacity option: 
$( ".selector" ).sortable({ opacity: 0.5 });
After initialization, get or set the opacity option: 
// getter
var opacity = $( ".selector" ).sortable( "option", "opacity" );

// setter
$( ".selector" ).sortable( "option", "opacity", 0.5 );
 false
placeholder String A class name to apply to the placeholder. Otherwise, a white space.

Code examples:
Initialize a sortable with the specified placeholder option: 
$( ".selector" ).sortable({ placeholder: "sortable-placeholder" });
After initialization, get or set the placeholder option: 
// getter
var placeholder = $( ".selector" ).sortable( "option", "placeholder" );

// setter
$( ".selector" ).sortable( "option", "placeholder", "sortable-placeholder" );
 false
revert Boolean or Number Whether the sortable items should revert to their new positions using a smooth animation.

Multiple types supported:
  • Boolean: When set to true, the item will use an animation, with the default duration.
  • Number: The duration of the animation, in milliseconds.
Code examples:
Initialize a sortable with the specified revert option: 
$( ".selector" ).sortable({ revert: true });
After initialization, get or set the revert option: 
// getter
var revert = $( ".selector" ).sortable( "option", "revert" );

// setter
$( ".selector" ).sortable( "option", "revert", true );
 false
← Api FocusApi Selectable →

📂 Categories