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.

See Also:

• Smooth Touch-enabled Selectable Library – selection.js
• Advanced Draggable & Selectable Library – DragSelect

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
    container: document.body,
    // CSS selector
    filter: ".ui-selectable",
    // defines descendants of selectable elements where selection can only be started when interacting with them.
    handle: false,
    // how far the lasso overlaps a selectable element before it's highlighted for selection.
    // "touch" or "fit"
    tolerance: "touch",
    // enables touch controls.
    touch: true,
    // 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);
// attaches all the instance's event listeners
selectable.attachEvents();
// 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 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 unselected items.
selectable.getUnSelectedItems();
// returns an Array of all selected element nodes
selectable.getSelectedNodes();
// returns an Array of all unselected element nodes.
selectable.getUnSelectedNodes();
// returns the first selected item in the list.
selectable.getFirstSelectedItem();
// returns the first selected element node in the list.
selectable.getFirstSelectedNode();
// re-init the instance
selectable.init();
// inverts the selection
selectable.invert();
// adds a custom event listener to an instance.
selectable.on(eventName, callback);
// adds a custom event listener to an instance that will be removed after being fired.
selectable.once(eventName, callback);
// reverts the current state to last state that was undone.
selectable.redo();
// 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);
// toggles the state of the given item(s)
// the second optional argument accepts a boolean to force the selected state.
selectable.toggle(choice, bool);
// reverts the current state to previous one (if one exists).
selectable.undo();
// updates the instance
selectable.update();

Events handlers available.

var selectable = new Selectable();
// selectable.on('method', fn);
// selectable.off('method', fn);
// selectable.once('method', fn);
selectable.on("init", function() {
  // when ready
});
selectable.on("destroyed", function() {
  // when destroyed
});
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("select", function(item) {
  // Fires when an item is selected.
});
selectable.on("selecting", function(item) {
  // Fires when an item is marked for selection.
});
selectable.on("deselect", function(item) {
  // Fires when an item is unselected.
});
selectable.on("deselecting", function(item) {
  // Fires when an item is marked for deselection.
});
selectable.on("add", function(item) {
  // Fires when an item is added.
});
selectable.on("remove", function(item) {
  // Fires when an item is removed
});
selectable.on("update", function(items) {
  // Fires when the instance is updated.
});
selectable.on("state.save", function() {
  // Fires when the current selection is saved.
});
selectable.on("state.undo", function() {
  // Fires when the state is undone.
});
selectable.on("state.redo", function() {
  // Fires when the state is redone.
});
selectable.on("enabled", function() {
  // Fires when the instance is enabled.
});
selectable.on("disabled", function() {
  // Fires when the instance is disabled.
});

Changelog:

v0.22.0 (10/13/2023)

• Added once() method to allow an event to be fired once only
• Added undo() and redo() methods as aliases of state(‘undo’) and state(‘redo’) respectively
• Added handle option to only allow selection to start from that element
• Added destroyed event
• Changed toggle() method to allow passing a boolean as the second argument to force the state
• Deprecated bind() and unbind() methods and added more semantic attachEvents() and detachEvents()
• Deprecated appendTo option and added the container option as a replacement
• Fixed mouseover event not being removed when destroying or disabling an instance
• Replaced slower forEach loops
• Removed the classList shim in favour of the native Element.classList property

v0.21.0 (10/11/2023)

• Changed appendTo option to container

v0.20.0 (10/09/2023)

• Added ‘selecting’ event
• Removed selectable.* prefixes from event names

v0.19.2 (08/09/2023)

• fix: unbind the correct function on mobile

v0.19.1 (07/02/2022)

• Bugfix

v0.19.0 (06/17/2022)

• Bugfixes

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