Smooth Touch-enabled Selectable Library – selection.js

Preview:

Description:

selection.js is a pure JavaScript library which enables the smooth, touch-friendly selectable functionality on a group of DOM elements.

The library allows the user to select multiple DOM elements with mouse drag and touch gestures. threshold in pixels

Basic usage:

Installation.

# NPM
$ npm install @simonwep/selection-js --save

<script src="selection.js"></script>

Insert a group of DOM elements into the document.

<section class="example">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
  ...
</section>

Initialize the selection.js.

Selection.create({
  containers: ['.example'],
  selectables: ['.example'],
  boundarys: ['.example']
});

Apply your own CSS styles to the selection area.

.selection-area {
  background: rgba(0, 0, 255, 0.1);
  border-radius: 0.1em;
  border: 0.05em solid rgba(0, 0, 255, 0.2);
}

Default configuration options.

Selection.create({

  // CSS class of selection area
  class: 'selection-area',

  // or cover (cover the entire element), center (touch the center)
  mode: 'touch',

  // threshold in pixels
  startThreshold: 0,

  // single-click selection
  singleClick: true,

  // enable/disable touch events
  disableTouch: false,

  // container element(s)
  containers: [],

  // selectable element(s)
  selectables: [],

  // start element(s)
  startareas: ['html'],

  // on scrollable areas the number on px per frame is devided by this amount.
  scrollSpeedDivider: 10,

  // boundary element(s)
  boundarys: ['html']
  
});

Functions and callbacks available.

Selection.create({

  // Will be called before the selection starts (mouse / touchdown). Can be used
  // to specify which action / mousebutton are needed to start the selection.
  validateStart(evt) {
    evt; // MouseEvent or TouchEvent

    // Return true to start the selection, false to cancel it.
    return true;
  },

  // on start 
  onStart(evt) {
    evt.selection;
    evt.eventName;
    evt.areaElement;
    evt.originalEvent;
    evt.selectedElements;
    evt.changedElements;
  },

  // on move
  onMove(evt) {
    // Same properties as onStart
  },

  // on stop
  onStop(evt) {
    // Same properties as onStart
  },

  // Element selection has stardet
  startFilter(evt) {
    evt.selection; // This selection instance
    evt.eventName; // The event name
    evt.element;   // The element from where the user stardet the selection             
    // return false to cancel the selection process
  },
               
  // Element selection has stardet
  selectionFilter(evt) {
      evt.selection; // This selection instance
      evt.eventName; // The event name
      evt.element;   // The element which is in the current selection               
      // return true to keep the element
  },

});

API methods.

// disable
selection.disable();

// enable
selection.enable();

// destroy
selection.destroy();

// save the current selected elements and append those to the next selection
selection.keepSelection();

// clear the previous selection
selection.clearSelection();

// get selected elements as an array
selection.getSelection();

// remove a particular element from the current selection.
selection.removeFromSelection(el:HTMLElement);

// need to be called if during a selection elements have been added
selection.resolveSelectables();

Changelog:

08/13/2020

• v1.7.1

02/30/2020

• v1.7.0

02/20/2020

• v1.6.0

01/18/2020

• v1.4.2/3: Fix unintented horizontal scrolling

12/08/2019

• v1.4.1: Fix invalid zIndex value for clipping-element

11/20/2019

• v1.4.0

10/16/2019

• v1.3.0

09/21/2019

• v1.2.1

08/07/2019

• v1.2.0

07/25/2019

• v1.1.1

07/11/2019

• v1.1.0

07/09/2019

• v1.0.0

06/15/2019

• v0.2.5

06/07/2019

• v0.2.4

05/23/2019

• v0.2.3

04/27/2019

• v0.2.2

02/14/2019

• v0.2.1: Add resolveSelectables to manually update selectables

01/03/2019

• v0.2.0

11/13/2018

• v0.1.5: Remove unused devDependencie and some spellfixes

10/28/2018

• Improve performance

10/27/2018

• Autoscroll and select vertical

10/26/2018

• Fix edge bug

10/25/2018

• Improve performance in critical passages

10/24/2018

• v0.1.4

10/14/2018

• Add destroy function

v0.1.3 (09/08/2018)

• Update

v0.1.2 (09/06/2018)

• Add validateStart option

v0.1.1 (07/28/2018)

• Update

07/22/2018

• refactoring and simplification inspired by golang