jQuery UI API - Selectable Widget
Category
Usage
Description: Use the mouse to select individual or a group of elements.
Version Added: 1.0
Dependencies:
Note: The jQuery UI Selectable plugin allows elements to be selected by dragging a box (sometimes called a lasso) with the mouse. Elements can be selected by clicking on them individually, or by dragging a selection area 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's specific CSS file as a starting point.
Quick Navigation
| Options | Methods | Events |
|---|---|---|
| appendTo autoRefresh cancel delay disabled distance filter tolerance | destroy disable enable option refresh widget | create selected selecting start stop unselected unselecting |
| Option | Type | Description | Default Value |
|---|---|---|---|
| appendTo | Selector | Which element the selection helper (lasso) should be appended to. <br> Code example: Initialize the selectable with the specified appendTo option: $( ".selector" ).selectable({ appendTo: "#someElem" }); After initialization, get or set the appendTo option: // getter<br>var appendTo = $( ".selector" ).selectable( "option", "appendTo" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "appendTo", "#someElem" ); | "body" |
| autoRefresh | Boolean | This option determines whether the position and size of each selectee is updated at the start of each select operation. If you have a large number of items, you may want to set this to false and call the refresh() method manually. <br> Code example: Initialize the selectable with the specified autoRefresh option: $( ".selector" ).selectable({ autoRefresh: false }); After initialization, get or set the autoRefresh option: // getter<br>var autoRefresh = $( ".selector" ).selectable( "option", "autoRefresh" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "autoRefresh", false ); | true |
| cancel | Selector | Prevents selecting from starting on specified elements. <br> Code example: Initialize the selectable with the specified cancel option: $( ".selector" ).selectable({ cancel: "a,.cancel" }); After initialization, get or set the cancel option: // getter<br>var cancel = $( ".selector" ).selectable( "option", "cancel" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "cancel", "a,.cancel" ); | "input, textarea, button, select, option" |
| delay | Number | The time in milliseconds between when the mouse button is pressed and when the selection starts. This option prevents unnecessary selection when clicking on an element. <br> Code example: Initialize selectable with the specified delay option: $( ".selector" ).selectable({ delay: 150 }); After initialization, get or set the delay option: // getter<br>var delay = $( ".selector" ).selectable( "option", "delay" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "delay", 150 ); | 0 |
| disabled | Boolean | If set to true, disables the selectable. <br> Code example: Initialize selectable with the specified disabled option: $( ".selector" ).selectable({ disabled: true }); After initialization, get or set the disabled option: // getter<br>var disabled = $( ".selector" ).selectable( "option", "disabled" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "disabled", true ); | false |
| distance | Number | The distance in pixels the mouse must be moved before selection starts. If this option is specified, selection will only start after the mouse has been dragged beyond the specified distance. This option prevents unnecessary selection when clicking on an element. <br> Code example: Initialize selectable with the specified distance option: $( ".selector" ).selectable({ distance: 30 }); After initialization, get or set the distance option: // getter<br>var distance = $( ".selector" ).selectable( "option", "distance" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "distance", 30 ); | 0 |
| filter | Selector | The matching child elements to make selectable. <br> Code example: Initialize selectable with the specified filter option: $( ".selector" ).selectable({ filter: "li" }); After initialization, get or set the filter option: // getter<br>var filter = $( ".selector" ).selectable( "option", "filter" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "filter", "li" ); | "*" |
| tolerance | String | Specifies the mode used to test whether the lasso should select an item. Possible values: <br> "fit": The lasso overlaps the item completely. <br> "touch": The lasso overlaps the item in any proportion. <br> Code example: Initialize selectable with the specified tolerance option: $( ".selector" ).selectable({ tolerance: "fit" }); After initialization, get or set the tolerance option: // getter<br>var tolerance = $( ".selector" ).selectable( "option", "tolerance" );<br> <br>// setter<br>$( ".selector" ).selectable( "option", "tolerance", "fit" ); | "touch" |
| Method | Returns | Description |
|---|---|---|
| destroy() | jQuery (plugin only) | Completely removes the selectable functionality. This will return the element to its pre-initialization state. <br> This method does not accept any parameters. Code example: Call the destroy method: $( ".selector" ).selectable( "destroy" ); |
| disable() | jQuery (plugin only) | Disables the selectable. <br> This method does not accept any parameters. Example code: Call the disable method: $( ".selector" ).selectable( "disable" ); |
| enable() | jQuery (plugin only) | Enables the selectable. <br> This method does not accept any parameters. Example code: Call the enable method: $( ".selector" ).selectable( "enable" ); |
| option( optionName ) | Object | Gets the value currently associated with the specified optionName. <br> optionName<br> Type: String<br> Description: The name of the option to get. Example code: Call the method: var isDisabled = $( ".selector" ).selectable( "option", "disabled" ); |
| option() | PlainObject | Gets an object containing key/value pairs representing the current selectable options hash. <br> This method does not accept any parameters. Example code: Call the method: var options = $( ".selector" ).selectable( "option" ); |
| option( optionName, value ) | jQuery (plugin only) | Sets the value of the selectable option associated with the specified optionName. <br> optionName<br> Type: String<br> Description: The name of the option to set.<br> <br> value<br> Type: Object<br> Description: The value to set for the option. Example code: Call the method: $( ".selector" ).selectable( "option", "disabled", true ); |
| option( options ) | jQuery (plugin only) | Sets one or more options for the selectable. <br> options<br> Type: Object<br> Description: A map of option-value pairs to set. Example code: Call the method: $( ".selector" ).selectable( "option", { disabled: true } ); |
| refresh() | jQuery (plugin only) | Updates the position and size of each selectee element. This method can be used to manually recalculate the position and size of each selectee when the autoRefresh option is set to false. <br> This method does not accept any parameters. Example code: Call the refresh method: $( ".selector" ).selectable( "refresh" ); |
| widget() | jQuery | Returns a jQuery object containing the selectable element. <br> This method does not accept any parameters. Example code: Call the widget method: var widget = $( ".selector" ).selectable( "widget" ); |
| Event | Type | Description |
|---|---|---|
| create( event, ui ) | selectablecreate | Triggered when the selectable is created. <br> event<br> Type: Event<br> <br> ui<br> Type: Object Note: The ui object is empty but included for consistency with other events. Example code: Initialize the selectable with the specified create callback: $( ".selector" ).selectable({<br> create: function( event, ui ) {}<br>}); 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 is added to the selection. <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> selected<br> Type: Element<br> Description: The selectable item that was selected. Code example: Initialize a selectable with the specified selected callback: $( ".selector" ).selectable({<br> selected: function( event, ui ) {}<br>}); 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 being added to the selection. <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> selecting<br> Type: Element<br> Description: The current selectable item being selected. Code example: Initialize a selectable with the specified selecting callback: $( ".selector" ).selectable({<br> selecting: function( event, ui ) {}<br>}); Bind an event listener to the selectableselecting event: $( ".selector" ).on( "selectableselecting", function( event, ui ) {} ); |
| start( event, ui ) | selectablestart | Triggered at the beginning of the selection operation. <br> event<br> Type: Event<br> <br> ui<br> Type: Object Note: The ui object is empty, included here for consistency with other events. Code example: Initialize a selectable with the specified start callback: $( ".selector" ).selectable({<br> start: function( event, ui ) {}<br>}); 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. <br> event<br> Type: Event<br> <br> ui<br> Type: Object Note: The ui object is empty, included here for consistency with other events. Code example: Initialize a selectable with the specified stop callback: $( ".selector" ).selectable({<br> stop: function( event, ui ) {}<br>}); 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. <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> unselected<br> Type: Element<br> Description: The selectable item that was unselected. Code example: Initialize a selectable with the specified unselected callback: $( ".selector" ).selectable({<br> unselected: function( event, ui ) {}<br>}); 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 that is being unselected.
Code Example: Initialize selectable with specified unselecting callback:
$( ".selector" ).selectable({
unselecting: function( event, ui ) {}
});
Bind an event listener to the selectableunselecting event:
$( ".selector" ).on( "selectableunselecting", function( event, ui ) {} );
Example
A simple jQuery UI Selectable Widget.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery UI Selectable Widget Demo</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>