mobius1-selectable

Selectable

This is a conversion of the jQuery UI Selectable plugin with all dependencies removed. Functionality and options are identical to the jQuery UI version with some additions.

Selectable mimics the Windows file / directory behaviour, i.e. click and / or drag to select items, hold CTRL to select multiple or hold SHIFT to select consecutive groups of items.

Demo

---

Install

Bower

bower install mobius1-selectable --save

npm

npm install mobius1-selectable --save

---

Browser

Grab the files from one of the CDNs and include them in your page:

https://unpkg.com/mobius1-selectable@latest/selectable.min.js

//or

https://cdn.jsdelivr.net/npm/mobius1-selectable@latest/selectable.min.js

You can replace latest with the required release number if needed.

---

Initialise the plugin:

const selectable = new Selectable(options);

---

Options

Option	Type	Default	Effect
filter	string or array	"*"	The elements that can be selected. You can pass either a CSS3 selector string or a collection of nodes.
appendTo	string or object	document.body	The container element to append the lasso to.
tolerance	string	touch	How far the lasso overlaps an element before it's highlighted. "fit" (lasso overlaps the item entirely) or "touch" (lasso overlaps the item by any amount).
autoRefresh	boolean	true	Recalculate the coords of the items. Set to false if you know the selectable items won't move or change size.
lasso	object		Style the lasso. Must be an object of valid CSS declarations.

Events

// Intitialise Selectable
const selectable = new Selectable(options);

// Listen for the 'selectable.XXXX' event
selectable.on('selectable.XXXX', function() {
    // Do something when 'selectable.XXXX' fires
});

• selectable.down fires on mousedown (within container)
• selectable.drag fires when dragging the lasso
• selectable.up fires on mouse up (within container)
• selectable.selected fires on each element selected

/**
 * @param item - the first item selected
 * @return {object}
 */
selectable.on('selectable.down', function(item) {
	// Do something when selectable.down fires
});

/**
 * @param coords - lasso coords (x1, x2, y1, y2)
 * @return {object}
 */
selectable.on('selectable.drag', function(coords) {
	// Do something when selectable.drag fires
});

/**
 * @param selectedItems - returns an array of selected items (objects)
 * @return {array}
 */
selectable.on('selectable.up', function(selectedItems) {
	// Do something when selectable.up fires
});

/**
 * @param item - the selected item (fires for each item that is selected)
 * @return {object}
 */
selectable.on('selectable.selected', function(item) {
	// Do something when selectable.selected fires
});

Note that items returned by these events are objects of the following format:

{
    element: HTMLElement, // the element
    index: Numbe,r // the position of the item in the list
    rect: DOMRect Object, // the element's bounding rects
    startselected: Boolean,
    selected: Boolean, // is the item currently selected
    selecting: Boolean, // is the item currently being selected
    unselecting: Boolean // is the item currently being deselected
}

Copyright © 2017 Karl Saunders | BSD & MIT license