Author: | Simonwep |
---|---|
Views Total: | 50 views |
Official Page: | Go to website |
Last Update: | April 11, 2023 |
License: | MIT |
Preview:

Description:
selection.js is a pure JavaScript library that enables 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.
See Also:
- Advanced Draggable & Selectable Library – DragSelect
- Touch-enabled Selectable Plugin With JavaScript – Selectable.js
Basic usage:
1. Install and import the selection.js.
# NPM $ npm install @viselect/vanilla --save
import SelectionArea from "@viselect/vanilla";
// OR import SelectionArea from "https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.mjs"
// OR <script src="https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.umd.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({ // Class for the selection-area itself (the element). selectionAreaClass: 'selection-area', // Class for the selection-area container. selectionContainerClass: 'selection-area-container', // Query selector or dom-node to set up container for the selection-area element. container: 'body', // document object - if you want to use it within an embed document (or iframe). document: window.document, // 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'], // Behaviour related options. behaviour: { // Specifies what should be done if already selected elements get selected again. // invert: Invert selection for elements which were already selected // keep: Keep selected elements (use clearSelection() to remove those) // drop: Remove stored elements after they have been touched overlap: 'invert', // 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', // 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: , y: }. startThreshold: 10, // 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, // This property defines the virtual inset margins from the borders of the container // component that, when crossed by the mouse/touch, trigger the scrolling. Useful for // fullscreen containers. startScrollMargins: {x: 0, y: 0} } }, // Features. features: { // Enable / disable touch support. touch: true, // Range selection. range: true, // 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' } } });
6. Event handlers.
selection.on('beforestart', evt => { console.log('beforestart', evt); }); selection.on('beforedrag', 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); // update the list of selectables selection.resolveSelectables(); // clear the previous selection selection.clearSelection(store:boolean = true); // get selected elements as an array selection.getSelection(); // return the selection area element. selection.getSelectionArea(); // 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:
v3.2.7 (04/11/2023)
- Bug fixes
v3.2.6 (03/30/2023)
- Bug fixes
v3.2.5 (01/19/2023)
- Bug fixes
v3.2.4 (01/06/2023)
- Bug fixes
- Changed dist js name
v3.2.3 (12/29/2022)
- Add missing events for the react / preact / vue packages.
v3.2.2 (11/25/2022)
- Update
v3.2.0 (11/23/2022)
- It’s now possible to pass an id to the contain in react/preact
- getComposePath is now stable enough to use it directly instead of using a polyfill
- clearSelection now behaves the same way as deselect and triggers both the move and stop events – less things to handle yourself when clearing a selection
- Remove legacy trigger function and do no longer return a boolean in deselect
- Bugfix
v3.1.0 (09/03/2022)
- Bug fixes
- Dependency updates, the react-package for example is now using createRoot.
v3.0.0 (07/15/2022)
- <script setup> is now used for the vue component which gives us full type-script support for the SelectionArea-component.
- The current selection is now available in the stop-event.
v2.1.2 (07/05/2021)
- destroy now not only removes the selection-area but cancels the selection and removes all event-listeners
v2.1.1 (06/03/2021)
- Fix no longer applied z-index on clipping element
v2.1.0 (06/03/2021)
- Minor improvements to how selection works when you’re pressing shift
- Selection is now more OS-like
v2.0.3 (06/03/2021)
- preventDefault is no longer called during selection. You’ll now have full control over text-selection.
v2.0.0beta (12/30/2020)
- API & Options updated
Looks like a great library! Already using it in one of my projects! Thanks to the author 🙂