Skip to content

🖱️ Selection - A simple and lightweight library to realize visual DOM Selections, like on your Desktop. No jQuery. Supports any CSS library, e.g. Bootstrap. Including vertical & horizontal scroll support.

Branch: master
Go to file
Code

Latest commit

Simonwep committed 57d7279 Jun 6, 2020
…t-extensions-0.1.4

Bump websocket-extensions from 0.1.3 to 0.1.4

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
st
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Logo

Simple and easy selection library to enable visual DOM-Selection

License MIT No dependencies Support me jsdelivr hits Build Status downloads per week gzip size brotli size Current version

Demo

Fully Featured demo

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.

You may want to checkout the source used in the demo-page, it's easier than reading through the manual.

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 => {
    
    // Use this event to decide whether a selection should take place or not.
    // For example if the user should be able to normally interact with input-elements you 
    // may want to prevent a selection if the user clicks such a element:
    // selection.on('beforestart', ({oe}) => {
    //   return oe.target.tagName !== 'INPUT'; // Returning false prevents a selection
    // });
    
    console.log('beforestart', evt);
}).on('start', evt => {

    // A selection got initiated, you could now clear the previous selection or
    // keep it if in case of multi-selection.
    console.log('start', evt);
}).on('move', evt => {

    // Here you can update elements based on their state.
    console.log('move', evt);
}).on('stop', evt => {

    // The last event can be used to call functions like keepSelection() in case the user wants
    // to select multiple elements.
    console.log('stop', evt);
});

You can find event-related examples here.

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.

About

🖱️ Selection - A simple and lightweight library to realize visual DOM Selections, like on your Desktop. No jQuery. Supports any CSS library, e.g. Bootstrap. Including vertical & horizontal scroll support.

Topics

Resources

License

You can’t perform that action at this time.