Selection - A simple and lightweight library to realize visual DOM Selections. No jQuery. Supports any CSS library
JavaScript HTML CSS
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Logo

Simple and easy selection library to enable visual DOM-Selection

License MIT Javascript ES6 npm package downloads per week Current version No dependencies

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@0.0.8/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,

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

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

Todos / Ideas

  • Keep selection option -> select multiple times.
  • Select via single-click.