README.md

Simple and easy selection library to enable visual DOM-Selection

Fully Featured demo

How it works

Features

• Supports touch devices
• Ultra small
• Highly optimized
• 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 selection = new Selection({
  // 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,

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

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

  // Browsers handle mouse-wheel events differently, this number will be used as
  // numerator to calculate the mount of px while scrolling manually: manualScrollSpeed / scrollSpeedDivider
  manualScrollSpeed: 750
});

Events

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

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 dragged the mouse around.
stop	The user stopped the selection, called on mouseup and touchend / touchcancel after a selection.

Every event-object contains the folling properties:

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

Example:

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

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.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.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 appends elements to the selection, can be a / an array of queries / elements. Returns actual selected elements as array.

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