Smooth Touch-enabled Selectable Library – selection.js

Preview:

Description:

selection.js is a pure JavaScript library that 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.

Basic usage:

1. Install and import the selection.js.

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

import SelectionArea from "https://cdn.jsdelivr.net/npm/@simonwep/selection-js/lib/selection.min.mjs"

<script src="https://cdn.jsdelivr.net/npm/@simonwep/selection-js/lib/selection.min.js"></script>

2. Create a group of DOM elements to be selectable.

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

3. Initialize the library and determine which elements are selectable.

const selection = new SelectionArea({
      // All elements in this container can be selected
      selectables: ['.example > div'],
      // The container is also the boundary in this case
      boundaries: ['.example']
}).

4. Apply your own CSS styles to the selection area.

.selection-area {
  background: rgba(46, 115, 252, 0.11);
  border: 2px solid rgba(98, 155, 255, 0.81);
  border-radius: 0.1em;
}

5. All default configuration options.

const selection = new SelectionArea({

      // document object - if you want to use it within an embed document (or iframe).
      document: window.document,

      // Class for the selection-area element.
      class: 'selection-area',

      // Query selector or dom-node to set up container for the selection-area element.
      container: 'body',

      // Query selectors for elements which can be selected.
      selectables: [],

      // Query selectors for elements from where a selection can be started from.
      startareas: ['html'],

      // Query selectors for elements which will be used as boundaries for the selection.
      boundaries: ['html'],

      // px, how many pixels the point should move before starting the selection (combined distance).
      // Or specifiy the threshold for each axis by passing an object like {x: <number>, y: <number>}.
      startThreshold: 10,

      // Enable / disable touch support
      allowTouch: true,

      // On which point an element should be selected.
      // Available modes are cover (cover the entire element), center (touch the center) or
      // the default mode is touch (just touching it).
      intersect: 'touch',

      // Configuration in case a selectable gets just clicked.
      singleTap: {

        // Enable single-click selection (Also disables range-selection via shift + ctrl).
        allow: true,
        
        // 'native' (element was mouse-event target) or 'touch' (element visually touched).
        intersect: 'native'
      },

      // Scroll configuration.
      scrolling: {

          // On scrollable areas the number on px per frame is devided by this amount.
          // Default is 10 to provide a enjoyable scroll experience.
          speedDivider: 10,

          // Browsers handle mouse-wheel events differently, this number will be used as 
          // numerator to calculate the mount of px while scrolling manually: manualScrollSpeed / scrollSpeedDivider.
          manualSpeed: 750
      }

}).

6. Event handlers.

selection.on('beforestart', evt => {
  console.log('beforestart', evt);
});

selection.on('start', evt => {
  console.log('start', evt);
});

selection.on('move', evt => {
  console.log('move', evt);
});

selection.on('stop', evt => {
  console.log('stop', evt);
});

7. API methods.

// disable
selection.disable();

// enable
selection.enable();

// destroy
selection.destroy();

// cancel the current selection process.
selection.cancel();

// manually trigger the start of a selection
// if silent is set to true, no beforestart event will be fired
selection.trigger(evt:MouseEvent | TouchEvent, silent: boolean = true)

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

// clear the previous selection
selection.clearSelection(store:boolean = true);

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

// manually append elements to the selection, can be a / an array of queries / elements 
// returns actual selected elements as array.
selection.select(query:(String | Element)[])

// remove a particular element from the current selection
// silent determines whether the move event should be fired
selection.deselect(el:HTMLElement, silent: boolean = true)

Changelog:

v2.1.2 (07/05/2020)

• destroy now not only removes the selection-area but cancels the selection and removes all event-listeners

v2.1.1 (06/03/2020)

• Fix no longer applied z-index on clipping element

v2.1.0 (06/03/2020)

• Minor improvements to how selection works when you’re pressing shift
• Selection is now more OS-like

v2.0.3 (06/03/2020)

• preventDefault is no longer called during selection. You’ll now have full control over text-selection.

v2.0.0beta (12/30/2020)

• API & Options updated

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