Author: | Simonwep |
---|---|
Views Total: | 34 views |
Official Page: | Go to website |
Last Update: | December 30, 2020 |
License: | MIT |
Preview:

Description:
selection.js is a pure JavaScript library that enables the smooth, touch-friendly selectable functionality on a group of DOM elements.
The library allows the user to select multiple DOM elements with mouse drag and touch gestures.
Basic usage:
1. Install and import the selection.js.
# NPM $ npm install @simonwep/selection-js --save
import SelectionArea from "https://cdn.jsdelivr.net/npm/@simonwep/selection-js/lib/selection.min.mjs"
<script src="https://cdn.jsdelivr.net/npm/@simonwep/selection-js/lib/selection.min.js"></script>
2. Create a group of DOM elements to be selectable.
<section class="example"> <div>Item 1</div> <div>Item 2</div> <div>Item 3</div> <div>Item 4</div> ... </section>
3. Initialize the library and determine which elements are selectable.
const selection = new SelectionArea({ // All elements in this container can be selected selectables: ['.example > div'], // The container is also the boundary in this case boundaries: ['.example'] }).
4. Apply your own CSS styles to the selection area.
.selection-area { background: rgba(46, 115, 252, 0.11); border: 2px solid rgba(98, 155, 255, 0.81); border-radius: 0.1em; }
5. All default configuration options.
const selection = new SelectionArea({ // document object - if you want to use it within an embed document (or iframe). document: window.document, // Class for the selection-area element. class: 'selection-area', // Query selector or dom-node to set up container for the selection-area element. container: 'body', // Query selectors for elements which can be selected. selectables: [], // Query selectors for elements from where a selection can be started from. startareas: ['html'], // Query selectors for elements which will be used as boundaries for the selection. boundaries: ['html'], // 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, // Enable / disable touch support allowTouch: true, // 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). intersect: 'touch', // Configuration in case a selectable gets just clicked. singleTap: { // Enable single-click selection (Also disables range-selection via shift + ctrl). allow: true, // 'native' (element was mouse-event target) or 'touch' (element visually touched). intersect: 'native' }, // Scroll configuration. scrolling: { // On scrollable areas the number on px per frame is devided by this amount. // Default is 10 to provide a enjoyable scroll experience. speedDivider: 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. manualSpeed: 750 } }).
6. Event handlers.
selection.on('beforestart', evt => { console.log('beforestart', evt); }); selection.on('start', evt => { console.log('start', evt); }); selection.on('move', evt => { console.log('move', evt); }); selection.on('stop', evt => { console.log('stop', evt); });
7. API methods.
// disable selection.disable(); // enable selection.enable(); // destroy selection.destroy(); // cancel the current selection process. selection.cancel(); // manually trigger the start of a selection // if silent is set to true, no beforestart event will be fired selection.trigger(evt:MouseEvent | TouchEvent, silent: boolean = true) // save the current selected elements and append those to the next selection selection.keepSelection(); // clear the previous selection selection.clearSelection(store:boolean = true); // get selected elements as an array selection.getSelection(); // manually append elements to the selection, can be a / an array of queries / elements // returns actual selected elements as array. selection.select(query:(String | Element)[]) // remove a particular element from the current selection // silent determines whether the move event should be fired selection.deselect(el:HTMLElement, silent: boolean = true)
Changelog:
v2.0.0beta (12/30/2020)
- API & Options updated
08/13/2020
- v1.7.1
02/30/2020
- v1.7.0
02/20/2020
- v1.6.0
01/18/2020
- v1.4.2/3: Fix unintented horizontal scrolling
12/08/2019
- v1.4.1: Fix invalid zIndex value for clipping-element
11/20/2019
- v1.4.0
10/16/2019
- v1.3.0
09/21/2019
- v1.2.1
08/07/2019
- v1.2.0
07/25/2019
- v1.1.1
07/11/2019
- v1.1.0
07/09/2019
- v1.0.0
06/15/2019
- v0.2.5
06/07/2019
- v0.2.4
05/23/2019
- v0.2.3
04/27/2019
- v0.2.2
02/14/2019
- v0.2.1: Add resolveSelectables to manually update selectables
01/03/2019
- v0.2.0
11/13/2018
- v0.1.5: Remove unused devDependencie and some spellfixes
10/28/2018
- Improve performance
10/27/2018
- Autoscroll and select vertical
10/26/2018
- Fix edge bug
10/25/2018
- Improve performance in critical passages
10/24/2018
- v0.1.4
10/14/2018
- Add destroy function
v0.1.3 (09/08/2018)
- Update
v0.1.2 (09/06/2018)
- Add validateStart option
v0.1.1 (07/28/2018)
- Update
07/22/2018
- refactoring and simplification inspired by golang
Looks like a great library! Already using it in one of my projects! Thanks to the author 🙂