Simple and easy selection library to enable visual DOM-Selection

Fully Featured demo

Features

• Supports touch devices
• Simple usage
• No jQuery
• Vertical and horizontal scroll support

Install

Via npm

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

Include via jsdelivr.net

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

Usage

const options = {

  // All elements with the class 'selectable' selectable.
  selectables: ['.selectable']
};
const selection = Selection.create(options);

It's recommended to also specify a bounding area for the selection (see 'Options').

---

Options

const selection = new Selection({

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

    // px, how many pixels the point should move before starting the selection
    startThreshold: 10,

    // Disable the selection functionality for touch devices
    disableTouch: false,

    // 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',

    // 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
    selectionAreaContainer: 'body',

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

Events

Since version 1.2.x Selection-js is event-driven. Use the on(event, cb) and off(event, cb) functions to bind / unbind eventlistener.

Event	Description
init	Selectionjs got initialized, the element is present in the dom.
beforestart	The mousedown / touchstart got called inside a valid boundary.
start	User stardet the selection, the startThreshold got fulfilled.
move	The user dragged the mouse aroun.
stop	The user stopped the selection, called on mouseup and touchend / touchcancel after a selection.

Every event contains the folling properties:

{
    oe,   // Original mouse- / touchevent. 'undefined' in this init event.
    inst, // Selectionjs instance
    area, // Area element
    selected, // Array of selected elements
    changed: {
        added, // Added elements against the previous selection
        removed // Same as added but for removed elements
    }
}

Example:

selection.on('init', () => {
    console.log('init');
}).on('beforestart', () => {
    
    // This function can return "false" to abort the selection
    console.log('beforestart');
}).on('start', () => {
    console.log('start');
}).on('move', () => {
    console.log('move');
}).on('stop', () => {
    console.log('stop');
}).on('select', () => {
    console.log('select');
});

Methods

• selection.on(event:String, cb:Function) - Appends 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.option(name:String) - Returns the option by name.

• selection.option(name:String, value:Mixed) - Set a new option value.

• 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.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.removeFromSelection(el:HTMLElement) - Removes a particular element from the current selection.

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

• selection.select(query:[String]|String) - Manually adds elements to the selection, can be a / an array of queries / elements. Triggers onMove and onStop.

Events

Event properties of start, stop and move event.

• selection:Selection - Current selection object.
• eventName:String - The event name.
• areaElement:HTMLElement - The selection element.
• originalEvent:Event - The original mouse-event.
• selectedElements:Array[HTMLElements] - Array with currently selected HTMLElements.
• changedElements:Object
• added:Array[HTMLElements] - Elements which are added to selectedElements since the last interaction (mousemove).
• removed:Array[HTMLElements] - Elements which are removed from selectedElements since last interaction (mousemove).

Filter event

Will be called on every selection, can be used to ignore specific elements in the current selection.

• selection:Selection - Current selection object.
• eventName:String - The event name.
• element:HTMLElement - HTMLElement, return false if you didn't want it in the selection.

Static methods

Selection

• Selection.create(options:Object):Selection - Creates a new instance.

Selection.utils

• on(el:HTMLElement, event:String, fn:Function[, options :Object]) - Attach an event handler function.
• off(el:HTMLElement, event:String, fn:Function[, options :Object]) - Remove an event handler.
• css(el:HTMLElement):Object - Get all css properties from this element.
• css(el:HTMLElement, attr:String):Mixed - Get the value from a style property.
• css(el:HTMLElement, attr:String, val:String) - Set a specific style property.
• css(el:HTMLElement, attr:Object) - Set multiple style properties.
• intersects(ela:HTMLElement, elb:HTMLElement):Boolean - Check if an HTMLElement intersects another.
• selectAll(selector:String|Array):Array - Returns all HTMLElements which were selected by the selector.
• eventPath(evt:DOMEvent):NodeList - Event.composedPath() polyfill.
• removeElement(arr:Array, el:Object) - Removes an particular element from an Array.