Touch-enabled Selectable Plugin With JavaScript – Selectable.js

Preview:

Description:

A performant, dependency-free, mobile-friendly, and fully configurable JavaScript Selectable plugin which allows you to select multiple elements using mouse drag and touch swipe.

How to use it:

Install it with package managers.

# NPM
$ npm install selectable --save
# Bower
$ bower install selectable --save

Import the ‘Selectable’ into your project or include the JavaScript file directly:

<script src='selectable.min.js'></script>

Add the CSS class ‘ui-selectable’ to the target elements.

<div id="container">
  <div class="box ui-selectable">
    1
  </div>
  <div class="box ui-selectable">
    2
  </div>
  <div class="box ui-selectable">
    3
  </div>
  <div class="box ui-selectable">
    4
  </div>
  <div class="box ui-selectable">
    5
  </div>
  <div class="box ui-selectable">
    6
  </div>
  <div class="box ui-selectable">
    7
  </div>
  <div class="box ui-selectable">
    8
  </div>
  ...
</div>

Initialize the Selectable plugin and done.

var selectable = new Selectable({
    // options here
});

Possible options to customize the Selectable plugin.

var selectable = new Selectable({
    // allows toggling of the item state.
    toggle: false,
    // auto refresh
    autoRefresh: true,
    // the minimum interval in milliseconds to wait before another resize or scroll callback is invoked.
    // higher numbers will increase scroll performance, but can delay item highlighting when auto scrolling.
    throttle: 50,
    // parent container
    appendTo: document.body,
    // CSS selector
    filter: ".ui-selectable",
    // how far the lasso overlaps a selectable element before it's highlighted for selection.
    // "touch" or "fit"
    tolerance: "touch",
    // Set to "sequential" to allow the lasso to select items sequentially instead of only the ones within the lasso.
    lassoSelect: "normal",
    // auto scroll when selecting
    autoScroll: {
      threshold: 0,
      increment: 10,
    },
    // sets default ignore items
    ignore: false,
    // auto saves the current selection on mouseup / touchend. 
    saveState: false,
    // limits the number of items that can be selected
    maxSelectable: false,
    // style the lasso. Must be an object of valid CSS properties and values.
    lasso: {
      border: '1px dotted #000',
      backgroundColor: 'rgba(52, 152, 219, 0.2)',
    },
    // default CSS classes
    classes: {
      lasso: "ui-lasso",
      selected: "ui-selected",
      container: "ui-container",
      selecting: "ui-selecting",
      selectable: "ui-selectable",
      deselecting: "ui-deselecting"
    }
});

API methods.

var selectable = new Selectable();
// adds new items
selectable.add(items);
// deselects all items
selectable.clear();
// deselects specific items
selectable.deselect(items);
// destroys the instance
selectable.destroy();
// disables the instance
selectable.disable();
// enables the instance
selectable.enable();
// returns an item(s) reference
selectable.get(items);
// returns an Array of all items
selectable.getItems();
// returns an Array of all selectable element nodes
selectable.getNodes();
// returns an Array of all selected items
selectable.getSelectedItems();
// returns an Array of all selected element nodes
selectable.getSelectedNodes();
// re-init the instance
selectable.init();
// inverts the selection
selectable.invert();
// refreshes the items
selectable.refresh();
// removes items
selectable.remove(items);
// selects items
selectable.select();
// selects all items
selectable.selectAll();
// sets the selection container
selectable.setContainer(container);
// "save" - saves the current selection
// "undo" - moves back to the last selection
// "redo" - restores the last undone selection
// "clear" - removes all saved selections
selectable.state(command);
// updates the instance
selectable.update();
// get unselected items
selectable.getUnSelectedItems();
// get unselected nodes
selectable.getUnSelectedNodes();

Events handlers available.

var selectable = new Selectable();
// selectable.on('method', fn);
// selectable.off('method', fn);
selectable.on("init", function() {
  // when ready
});
selectable.on("start", function(item) {
  // Fires on mousedown / touchstart.
});
selectable.on("drag", function(coords) {
  // Fires on mousemove / touchmove.
});
selectable.on("end", function(selected, unselected) {
  // Fires on mouseup / touchend and touchcancel.
});
selectable.on("selecteditem", function(item) {
  // Fires when an item is selected.
});
selectable.on("deselecteditem", function(item) {
  // Fires when an item is unselected.
});
selectable.on("addeditem", function(item) {
  // Fires when an item is added.
});
selectable.on("removeditem", function(item) {
  // Fires when an item is removed
});
selectable.on("update", function(items) {
  // Fires when the instance is updated.
});
selectable.on("refresh", function() {
  // Fires when the instance is refreshed.
});
selectable.on("enabled", function() {
  // Fires when the instance is enabled.
});
selectable.on("disabled", function() {
  // Fires when the instance is disabled.
});

Changelog:

v0.18.0 (04/27/2022)

• Added getUnSelectedItems() method
• Added getUnSelectedNodes() method

v0.17.8 (09/08/2020)

• Fixed an error when using shift select and clicking container
• Fixed an error when using maxSelectable and toggle together
• Allow instance to be retrieved from parent element

v0.17.7 (06/29/2020)

• Fixed IE error

v0.17.6 (06/05/2020)

• Update license

v0.17.5 (04/25/2020)

• Fixed sequential select bug causing all elements from the first one to be selected when clicking outside item

12/16/2019

• Fix states

07/24/2019

• v0.17.3: Incorrect selection on elements with translateX, translateY or translate3d applied.

04/23/2019

• Detect 2d transformed elements
• Fixed bug

04/17/2019

• v0.17.2: Added lassoSelect option.

02/25/2019

• v0.16.0: Add maxSelectable option to limit the number of selections.

12/09/2018

• v0.15.6: Allow CSS3 selector string to be passed to add(), remove() and get() methods.

12/09/2018

• v0.15.2: Fix touch controls

12/07/2018

• v0.15.1: Fix reference error, remove debug code

12/06/2018

• v0.14.1: Set spacebar to toggle active item

12/02/2018

• v0.14.0

11/29/2018

• v0.13.4

11/08/2018

• v0.13.3

10/31/2018

• v0.13.1: hotfix

10/30/2018

• v0.12.3

10/30/2018

• Fix lasso position when appending to body

v0.12.1 (10/29/2018)

• fix incorrect selection

v0.11.0 (09/30/2018)

• Default ignore value

v0.10.9 (06/15/2018)

• Destroying instance doesn’t remove all event handlers