Smooth Touch-enabled Selectable Library – viselect

viselect (formerly 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 viselect.

# 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,

    // De-select all if user clicks clicks outside selectables.
    // Disabled by default because it is not possible to reliably detect if the user clicked on a scrollbar.
    deselectOnBlur: false,

    // 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.10.0 (08/27/2026)

• Update

v3.9.0 (01/16/2025)

• Add getLocationArea, setLocationArea and getSelection functions to make custom-positioning possible

v3.8.1 (01/12/2025)

• Fix incorrect handling of behaviour.triggers when multiple are provided

v3.8.0 (01/03/2025)

• Updated for React

v3.7.1 (01/02/2025)

• Bugfixes

v3.7.0 (11/21/2024)

• Remove usage of DOMRect to allow unit testing it with jsdom and happy-dom
• Minor build improvements reducing the bundle size by ~5%

v3.6.0 (09/30/2024)

• Add new deselectOnBlur feature. If enabled, you can deselect elements by clicking next to a selectable inside of an boundary. Note that this may not work as expected in Safari due to having “invisible” overlay scrollbars.

v3.5.1 (04/25/2024)

• Bugfixes

v3.5.0 (12/17/2023)

• Add trigger option to specify mouse button and meta buttons to press when starting a selection
• Support custom container element in react packages

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

The post Smooth Touch-enabled Selectable Library – viselect appeared first on CSS Script.