Smooth Touch-enabled Selectable Library – selection.js

Preview:

Description:

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

See Also:

• Advanced Draggable & Selectable Library – DragSelect
• Touch-enabled Selectable Plugin With JavaScript – Selectable.js

Basic usage:

1. Install and import the selection.js.

# NPM
$ npm install @viselect/vanilla --save

import SelectionArea from "@viselect/vanilla";

// OR
import SelectionArea from "https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.mjs"

// OR
<script src="https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.umd.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({
  // Class for the selection-area itself (the element).
  selectionAreaClass: 'selection-area',
  // Class for the selection-area container.
  selectionContainerClass: 'selection-area-container',
  // Query selector or dom-node to set up container for the selection-area element.
  container: 'body',
  // document object - if you want to use it within an embed document (or iframe).
  document: window.document,
  // 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'],
  // Behaviour related options.
  behaviour: {
    // Specifies what should be done if already selected elements get selected again.
    //   invert: Invert selection for elements which were already selected
    //   keep: Keep selected elements (use clearSelection() to remove those)
    //   drop: Remove stored elements after they have been touched
    overlap: 'invert',
    // 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',
    // 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: , y: }.
    startThreshold: 10,
    // 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,
      // This property defines the virtual inset margins from the borders of the container
      // component that, when crossed by the mouse/touch, trigger the scrolling. Useful for
      // fullscreen containers.
      startScrollMargins: {x: 0, y: 0}
    }
  },
  // Features.
  features: {
    // Enable / disable touch support.
    touch: true,
    // Range selection.
    range: true,
    // 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'
    }
  }
});

6. Event handlers.

selection.on('beforestart', evt => {
  console.log('beforestart', evt);
});
selection.on('beforedrag', 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);
// update the list of selectables
selection.resolveSelectables();
// clear the previous selection
selection.clearSelection(store:boolean = true);
// get selected elements as an array
selection.getSelection();
// return the selection area element.
selection.getSelectionArea();
// 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:

v3.4.1 (11/13/2023)

• Fix not exported types in package.json exports

v3.4.0 (09/06/2023)

• Update dependencies

v3.3.1 (07/25/2023)

• Bug fixes

v3.3.0 (07/22/2023)

• Bug fixes

v3.2.7 (04/11/2023)

• Bug fixes

v3.2.6 (03/30/2023)

• Bug fixes

v3.2.5 (01/19/2023)

• Bug fixes

v3.2.4 (01/06/2023)

• Bug fixes
• Changed dist js name

v3.2.3 (12/29/2022)

• Add missing events for the react / preact / vue packages.

v3.2.2 (11/25/2022)

• Update

v3.2.0 (11/23/2022)

• It’s now possible to pass an id to the contain in react/preact
• getComposePath is now stable enough to use it directly instead of using a polyfill
• clearSelection now behaves the same way as deselect and triggers both the move and stop events – less things to handle yourself when clearing a selection
• Remove legacy trigger function and do no longer return a boolean in deselect
• Bugfix

v3.1.0 (09/03/2022)

• Bug fixes
• Dependency updates, the react-package for example is now using createRoot.

v3.0.0 (07/15/2022)

• <script setup> is now used for the vue component which gives us full type-script support for the SelectionArea-component.
• The current selection is now available in the stop-event.

v2.1.2 (07/05/2021)

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

v2.1.1 (06/03/2021)

• Fix no longer applied z-index on clipping element

v2.1.0 (06/03/2021)

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

v2.0.3 (06/03/2021)

• 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