Selection

Selection.js is an simple, lightweight, and modern library for making visual DOM Selections.

Quick demo: https://simonwep.github.io/selection

Features

• Supports touch devices
• Simple usage
• No jQuery
• Nodejs support
• Lightweight, 3KB gzipped

Install via npm

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

Or simply include it via script tag:

<script src="selection.min.js"></script>

Usage

const options = {

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

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

Options

const selection = new Selection({  

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

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

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

    // Query selectors from elements from which the siblings can be selected
    // Default: Empty array
    containers: [],

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

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

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

    // Element selection stardet             
    onStart(evt) {
        evt.selection;
        evt.eventName;
        evt.areaElement;
        evt.originalEvent;
        evt.selectedElements;
        evt.changedElements;
    },

    // Element selection move
    onMove(evt) {
       // Same properties as onStart
    },

    // Element selection stopped
    onStop(evt) {
       // Same properties as onStart
    },

    // Element selection has stardet
    startFilter(evt) {
        evt.selection; // This selection instance
        evt.eventName; // The event name
        evt.element;   // The element from where the user stardet the selection

        // return false to cancel the selection process
    },

    // Element selection has stardet
    selectionFilter(evt) {
        evt.selection; // This selection instance
        evt.eventName; // The event name
        evt.element;   // The element which is in the current selection

        // return true to keep the element
    },
});

Methods

• 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.

Events

start / stop / 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

• selection:Selection - Current selection object.
• eventName:String - The event name.
• element:HTMLElement - HTMLElement from which the selection starts.

Static methods

Selection

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

Selection.utils

• on(el:HTMLElement, event:String, fn:Function) - Attach an event handler function.
• off(el:HTMLElement, event:String, fn:Function) - 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() ponyfill.