jQuery UI API - Selectable Widget

Category

Interactions

Usage

Description:Select individual elements or a group of elements using the mouse.

Version added:1.0

Dependencies:

Notes:The jQuery UI Selectable plugin allows elements to be selected by dragging with the mouse (sometimes called a lasso). You can click or drag while holding down the ctrl/meta key to select multiple (non-contiguous) elements.

Additional notes:This widget requires some functional CSS, otherwise it will not work. If you create a custom theme, use the widget-specific CSS file as a starting point.

Quick Navigation

Options Methods Events

Options Type Description Default
appendTo Selector Which element the select helper (lasso) should be added to.

Code examples:

Initialize with the specifiedappendTooptions for draggable:

$( ".selector" ).selectable({ appendTo: "#someElem" });
    

After initialization, get or set theappendTooption:

// getter
var appendTo = $( ".selector" ).selectable( "option", "appendTo" );
 
// setter
$( ".selector" ).selectable( "option", "appendTo", "#someElem" );
    
 "body"
autoRefresh Boolean This option determines whether to update (recalculate) the position and size of each selectable item at the start of each selection operation. If you have many items, you may want to set this option to false and manually call therefresh()method.

Code examples:

Initialize with the specifiedautoRefreshoptions for draggable:

$( ".selector" ).selectable({ autoRefresh: false });
    

After initialization, get or set theautoRefreshoption:

// getter
var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );
 
// setter
$( ".selector" ).selectable( "option", "autoRefresh", false );
    
 true
cancel Selector Prevents selection from starting on elements that match the selector.

Code examples:

Initialize with the specifiedcanceloptions for selectable:

$( ".selector" ).selectable({ cancel: "a,.cancel" });
    

After initialization, get or set thecanceloption:

// getter
var cancel = $( ".selector" ).selectable( "option", "cancel" );
 
// setter
$( ".selector" ).selectable( "option", "cancel", "a,.cancel" );
    
 "input, textarea, button, select, option"
delay Number The time in milliseconds after a mouse down until the selection starts. This option can prevent unnecessary selections when clicking on an element.

Code examples:

Initialize with the specifieddelayoptions for selectable:

$( ".selector" ).selectable({ delay: 150 });
    

After initialization, get or set thedelayoption:

// getter
var delay = $( ".selector" ).selectable( "option", "delay" );
 
// setter
$( ".selector" ).selectable( "option", "delay", 150 );
    
 0
disabled Boolean If set totrue, the selectable is disabled.

Code examples:

Initialize with the specifieddisabledoptions for selectable:

$( ".selector" ).selectable({ disabled: true });
    

After initialization, get or set thedisabledoption:

// getter
var disabled = $( ".selector" ).selectable( "option", "disabled" );
 
// setter
$( ".selector" ).selectable( "option", "disabled", true );
    
 false
distance Number The distance in pixels that the mouse must move after a mouse down before the selection starts. If this option is specified, the selection only starts when the mouse is dragged beyond the specified distance. This option can prevent unnecessary selections when clicking on an element.

Code examples:

Initialize with the specifieddistanceoptions for selectable:

$( ".selector" ).selectable({ distance: 30 });
    

After initialization, get or set thedistanceoption:

// getter
var distance = $( ".selector" ).selectable( "option", "distance" );
 
// setter
$( ".selector" ).selectable( "option", "distance", 30 );
    
 0
filter Selector The matching child elements that are made selectable (can be selected).

Code examples:

Initialize with the specifiedfilteroptions for selectable:

$( ".selector" ).selectable({ filter: "li" });
    

After initialization, get or set thefilteroption:

// getter
var filter = $( ".selector" ).selectable( "option", "filter" );
 
// setter
$( ".selector" ).selectable( "option", "filter", "li" );
    
 "*"
tolerance String Specifies the mode used to test whether the lasso selects an item. Possible values:
  • "fit": The lasso completely overlaps the item.
  • "touch": The lasso overlaps the item, in any proportion.

Code examples:

Initialize with the specifiedtoleranceoptions for selectable:

$( ".selector" ).selectable({ tolerance: "fit" });
    

After initialization, get or set thetoleranceoption:

// getter
var tolerance = $( ".selector" ).selectable( "option", "tolerance" );
 
// setter
$( ".selector" ).selectable( "option", "tolerance", "fit" );
    
 "touch"

Methods Returns Description
destroy() jQuery (plugin only) Completely removes the selectable functionality. This returns the element back to its pre-initialization state.
  • This method does not accept any arguments.

Code examples:

Call the destroy method:

$( ".selector" ).selectable( "destroy" );
    
disable() jQuery (plugin only) Disables the selectable.
  • This method does not accept any arguments.

Code examples:

Call the disable method:

$( ".selector" ).selectable( "disable" );
    
enable() jQuery (plugin only) Enables the selectable.
  • This method does not accept any arguments.

Code examples:

Call the enable method:

$( ".selector" ).selectable( "enable" );
    
option( optionName ) Object Gets, for the currently specifiedoptionNamethe associated value.
  • optionName
    Type: String
    Description: The name of the option to get.

Code examples:

Call this method:

var isDisabled = $( ".selector" ).selectable( "option", "disabled" );
    
option() PlainObject Gets an object containing key/value pairs representing the current selectable options hash.
  • This method does not accept any arguments.

Code examples:

Call this method:

var options = $( ".selector" ).selectable( "option" );
    
option( optionName, value ) jQuery (plugin only) Sets, for the specifiedoptionNamethe value of the associated selectable option.
  • optionName
    Type: String
    Description: The name of the option to set.
  • value
    Type: Object
    Description: The value to set for the option.

Code examples:

Call this method:

$( ".selector" ).selectable( "option", "disabled", true );
    
option( options ) jQuery (plugin only) Sets one or more options for the selectable.
  • options
    Type: Object
    Description: The option-value pairs to set.

Code examples:

Call this method:

$( ".selector" ).selectable( "option", { disabled: true } );
    
refresh() jQuery (plugin only) Updates the position and size of each selectable element. When theautoRefreshoption is set to false, this method can be used to manually recalculate the position and size of each selectable item.
  • This method does not accept any arguments.

Code examples:

Call the refresh method:

$( ".selector" ).selectable( "refresh" );
    
widget() jQuery Returns ajQueryobject containing the selectable element.
  • This method does not accept any arguments.

Code examples:

Call the widget method:

var widget = $( ".selector" ).selectable( "widget" );
    

Events Type Description
create( event, ui ) selectablecreate Triggered when the selectable is created.
  • event
    Type: Event
  • ui
    Type: Object

Note:uiThe object is empty, and is included for consistency with other events.

Code examples:

Initialize the selectable with the specified create callback:

$( ".selector" ).selectable({
  create: function( event, ui ) {}
});
    

Bind an event listener to the selectablecreate event:

$( ".selector" ).on( "selectablecreate", function( event, ui ) {} );
    
selected( event, ui ) selectableselected Triggered at the end of the selection operation, when each element has been added to the selection.
  • event
    Type: Event
  • ui
    Type: Object
    • selected
      Type: Element
      Description: The selectable item that was selected.

Code examples:

Initialize the selectable with the specified selected callback:

$( ".selector" ).selectable({
  selected: function( event, ui ) {}
});
    

Bind an event listener to the selectableselected event:

$( ".selector" ).on( "selectableselected", function( event, ui ) {} );
    
selecting( event, ui ) selectableselecting Triggered during the selection operation, when each element is added to the selection.
  • event
    Type: Event
  • ui
    Type: Object
    • selecting
      Type: Element
      Description: The current selectable item being selected.

Code examples:

Initialize the selectable with the specified selecting callback:

$( ".selector" ).selectable({
  selecting: function( event, ui ) {}
});
    

Bind an event listener to the selectableselecting event:

$( ".selector" ).on( "selectableselecting", function( event, ui ) {} );
    
start( event, ui ) selectablestart Triggered at the start of the selection operation.
  • event
    Type: Event
  • ui
    Type: Object

Note:uiThe object is empty, and is included for consistency with other events.

Code examples:

Initialize the selectable with the specified start callback:

$( ".selector" ).selectable({
  start: function( event, ui ) {}
});
    

Bind an event listener to the selectablestart event:

$( ".selector" ).on( "selectablestart", function( event, ui ) {} );
    
stop( event, ui ) selectablestop Triggered at the end of the selection operation.
  • event
    Type: Event
  • ui
    Type: Object

Note:uiThe object is empty; it is included here for consistency with other events.

Code examples:

Initialize the selectable with the specified stop callback:

$( ".selector" ).selectable({
  stop: function( event, ui ) {}
});
    

Bind an event listener to the selectablestop event:

$( ".selector" ).on( "selectablestop", function( event, ui ) {} );
    
unselected( event, ui ) selectableunselected Triggered at the end of the selection operation, when each element is removed from the selection.
  • event
    Type: Event
  • ui
    Type: Object
    • unselected
      Type: Element
      Description: The selectable item that is no longer selected.

Code examples:

Initialize the selectable with the specified unselected callback:

$( ".selector" ).selectable({
  unselected: function( event, ui ) {}
});
    

Bind an event listener to the selectableunselected event:

$( ".selector" ).on( "selectableunselected", function( event, ui ) {} );
    
unselecting( event, ui ) selectableunselecting Triggered during the selection operation, when each element is removed from the selection.
  • event
    Type: Event
  • ui
    Type: Object
    • unselecting
      Type: Element
      Description: The current selectable item being unselected.

Code examples:

Initialize the selectable with the specified unselecting callback:

$( ".selector" ).selectable({
  unselecting: function( event, ui ) {}
});
    

Bind an event listener to the selectableunselecting event:

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

Examples

A simple jQuery UI Selectable Widget.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>可选择小部件（Selectable Widget）演示</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <style>
  #selectable .ui-selecting {
    background: #ccc;
  }
  #selectable .ui-selected {
    background: #999;
  }
  </style>
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
 
<ul id="selectable">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
  <li>Item 4</li>
  <li>Item 5</li>
</ul>
 
<script>
$( "#selectable" ).selectable();
</script>
 
</body>
</html>

Other Extensions