Visual dom-selection library

Features

• Tiny (only ~4kb)
• Simple usage
• Highly optimized
• Zero dependencies
• Mobile / touch support
• Vertical and horizontal scroll support

Install

Via npm:

$ npm install @simonwep/selection-js

Via yarn:

$ yarn add @simonwep/selection-js

Include via jsdelivr.net

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

Or using ES6 modules:

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

Usage

const selection = new SelectionArea({

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

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

    // 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
    touch: 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).
    mode: 'touch',

    // Behaviour on single-click
    // Available modes are 'native' (element was mouse-event target) or 'touch' (element got touched)
    tapMode: 'native',

    // Enable single-click selection (Also disables range-selection via shift + ctrl)
    singleClick: true,

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

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

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

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

    // 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
    }
});

Events

Use the on(event, cb) and off(event, cb) functions to bind / unbind event-listener.

You may want to checkout the source used in the demo-page, it's easier than reading through the manual.

Event	Description
beforestart	The mousedown / touchstart got called inside a valid boundary. Return false to cancel selection immediatly.
start	User started the selection, the startThreshold got fulfilled.
move	The user is selecting elements / moving the mouse around.
stop	The user stopped the selection, called on mouseup and touchend / touchcancel after a selection.

Check out types.ts to see what kind of data is passed to each event.

Example:

selection.on('beforestart', evt => {
    
    // Use this event to decide whether a selection should take place or not.
    // For example if the user should be able to normally interact with input-elements you 
    // may want to prevent a selection if the user clicks such a element:
    // selection.on('beforestart', ({event}) => {
    //   return event.target.tagName !== 'INPUT'; // Returning false prevents a selection
    // });
    
    console.log('beforestart', evt);
}).on('start', evt => {

    // A selection got initiated, you could now clear the previous selection or
    // keep it if in case of multi-selection.
    console.log('start', evt);
}).on('move', evt => {

    // Here you can update elements based on their state.
    console.log('move', evt);
}).on('stop', evt => {

    // The last event can be used to call functions like keepSelection() in case the user wants
    // to select multiple elements.
    console.log('stop', evt);
});

You can find event-related examples here.

Methods

• selection.on(event:String, cb:Function) - Adds an event listener to the given corresponding event-name (see section Events), returns the current instance so it can be chained.

• selection.off(event:String, cb:Function) - Removes an event listener from the given corresponding event-name (see section Events), returns the current instance so it can be chained.

• selection.disable() - Disable the functionality to make selections.

• selection.enable() - Enable the functionality to make selections.

• selection.destroy() - Unbinds all events and removes the area-element.

• selection.cancel() - Cancels the current selection process.

• selection.trigger(evt:MouseEvent|TouchEvent, silent:boolean) - Manually triggers the start of a selection. silent = true means that no beforestart event will get fired (default).

• selection.keepSelection() - Will save the current selected elements and will append those to the next selection. Can be used to allow multiple selections.

• selection.clearSelection() - Clear the previous selection (elements which were saved by keepSelection()).

• selection.getSelection() - Returns currently selected elements as an Array.

• selection.resolveSelectables() - Need to be called if during a selection elements have been added / removed.

• selection.select(query:[String]|String) - Manually appends elements to the selection, can be a / an array of queries / elements. Returns actual selected elements as array.

• selection.deselect(el:HTMLElement) - Removes a particular element from the current selection.