jquery.selectable.js - Turn a collection of HTML elements into a selectable list
Developed by Cory LaViska for A Beautiful Site, LLC
Licensed under the MIT license: http://opensource.org/licenses/MIT
This plugin provides a minimal, lightweight solution to turn a collection of HTML elements into a selectable list.
- Turn any collection of elements into a selectable list
- Supports single and multiple selections
- Flexible markup! Molds to your HTML and CSS.
- Customizable class names
- Customizable getter
- Callbacks for click, double click, change
- API to get, set, select all, select none, and disable selection
- Compact! (About 230 lines)
Include the minified version of this plugin in your project or install via NPM:
npm install --save @claviska/jquery-selectable
Attaching the plugin
Minimal example that attaches the plugin to a group of list items:
Item 1Item 2Item 3
This will let you select any
<li> inside of
.my-list by clicking on it. When an item is selected, it will receive the
active class by default. For flexibility, the plugin doesn't add styles to selected elements — this is left to your stylesheet.
Example with all possible options:
getValue: a getter function that returns the value of an element in your collection. By default, the plugin will use the
items: a selector used to group items into the collection. Defaults to
ato make a group of links selectable or
.my-classto make all items with a specific class selectable. (The selector will only match children of the container that you instantiated the plugin on.)
multiple: whether or not multiple selections are allowed. Defaults to
disabledClass: a class to apply to each item when the control is disabled. Defaults to
selectedClass: a class to apply to each selected item. Defaults to
All callbacks are called in the context of the respective container you instantiated the plugin on.
change callback, two arguments are available. The first is an array of selected values and the second is an array containing the selected elements.
click callback, three arguments are available. The first is the value of the target item, the second is the target element, and the third is the event.
change: runs when the selection changes, including when changes are made programmatically.
click: runs when an item is clicked. Returning false will prevent the selection from being toggled.
Using Anchors? If your selectable targets are
<a> elements, the plugin will automatically prevent clicks from hijacking the page — there's no need to use your own
event.preventDefault() on them.
Methods are called using this syntax:
The following API methods are supported:
change: Triggers the change event (will only run if a change has actually been made). Useful when you need to trigger a change after working with items directly in the DOM.
create(default): initializes the plugin on the given container.
destroy: returns the control to its pre-initialized state.
getElements: returns a jQuery object containing all elements in the collection. Passing
trueas an argument will return only selected elements. Passing a string or an array will return all elements that have those values.
selectAll: selects all items in the collection.
selectNone: clears selection from all items in the collection.
value: when no argument is passed, this method returns an array of values of the current selection. When a string or array is passed as an argument, this method will set the selection to any item matching the specified values.
- Fixed a bug where using the
clickcallback would prevent selection from being toggled.
- Removed the
doubleClickcallback. Users who need this are encouraged to attach their own listener and use the methods above to obtain the selected values and elements.
- Fixed a bug where using the