Selection - A simple and lightweight library to realize visual DOM Selections. No jQuery. Supports any CSS library, e.g. Bootstrap.
Clone or download
Latest commit d880ba4 Oct 13, 2018

README.md

Logo

Simple and easy selection library to enable visual DOM-Selection

License MIT Webpack No dependencies Support me Build Status npm package downloads per week Current version

Demo

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

Include via jsdelivr.net

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

Usage

const options = {

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

It's recommend 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
    singleClick: true,

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

    // 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'],
    
    // Will be called before the selection starts (mouse / touchdown). Can be used
    // to specify which action / mousebutton are needed to start the selection.
    validateStart(evt) {
        evt; // MouseEvent or TouchEvent
      
        // Return true to start the selection, false to cancel it.
        return true; 
    },

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

    // Single-click selection
    onSelect(evt) {
       // Same properties as onStart
       evt.target; // Clicked element
    },

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

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

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

  • 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 where saved by keepSelection()).

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

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

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

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.