Viselect - Vanilla
Installation
Via package manager
Install using your package manager of choice:
npm install @viselect/vanilla
Via script tags
<script src="https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.umd.js"></script>
Via ES6 import
import SelectionArea from "https://cdn.jsdelivr.net/npm/@viselect/vanilla/dist/viselect.mjs"
Getting started
Last but not least, you'll need to add some basic styles to make your selection-area visible:
.selection-area {
background: rgba(46, 115, 252, 0.11);
border: 2px solid rgba(98, 155, 255, 0.81);
border-radius: 0.1em;
}
Additionally, to not interfere with text-selection, selection-js won't prevent any default events anymore (as of v2.0.3
).
This, however, can cause problems with the actual selection ("introduced" by #99, reported in #103).
If you don't care about text-selection, add the following to the container where all your selectables are located:
.container {
user-select: none;
}
Configuration
const selection = new SelectionArea({
selectionAreaClass: 'selection-area',
selectionContainerClass: 'selection-area-container',
container: 'body',
document: window.document,
selectables: [],
startareas: ['html'],
boundaries: ['html'],
behaviour: {
overlap: 'invert',
intersect: 'touch',
startThreshold: 10,
triggers: [0],
scrolling: {
speedDivider: 10,
manualSpeed: 750,
startScrollMargins: {x: 0, y: 0}
}
},
features: {
touch: true,
range: true,
deselectOnBlur: false,
singleTap: {
allow: true,
intersect: 'native'
}
}
});
Events
Use the on(event, cb)
and off(event, cb)
functions to bind / unbind event-listener.
Event | Description |
---|
beforestart | The user tapped one of the areas within the specified boundaries. Return false to cancel selection immediatly. |
beforedrag | Same as beforestart but before the user starts selecting by dragging the mouse. Can be used to conditionally allow a selection by dragging. Return false to cancel the selection. |
start | Selection started, here you can decide if you want to keep your previously selected elements. |
move | Selection is active, user is moving the pointer around. |
stop | Selection has stopped. |
Functions
Function | Description |
---|
resolveSelectables(): void | Updates the list of selectables, useful if new elements have been added during a selection. |
getSelection(): Element[] | Returns currently selected element. Use it in the stop event to collect selected elements. |
getSelectionArea(): HTMLElement | Returns the selection area element. |
cancel(keepEvent = false): void | Cancel the currently active selection, pass true to trigger the stop event afterwards. |
destroy(): void | Destroy the SelectionArea -instance, removes all event-listeners and the selection-area element from the DOM. |
disable(): void | Disables the selection-area temporarily. |
enable(): void | Enables the selection-area. |
select(query: SelectAllSelectors, quiet = false): Element[] | Manually select elements, if quiet is set to true this will not fire the move & stop event. |
deselect(query: SelectAllSelectors, quiet = false): Element[] | Manually deselect elements, if quiet is set to true this will not fire the move & stop event. |
clearSelection(includeStored = true, quiet = false): void | Clears the selection, pass false to keep previously selected elements. If quiet is set to true this will not fire the move & stop event. |
trigger(evt: MouseEvent / TouchEvent, silent = true): void | Manually trigger a selection. |
Example
selection.on('beforestart', evt => {
console.log('beforestart', evt);
}).on('beforedrag', evt => {
console.log('beforedrag', evt);
}).on('start', evt => {
console.log('start', evt);
}).on('move', evt => {
console.log('move', evt);
}).on('stop', evt => {
console.log('stop', evt);
});
Virtual / dynamic lists
In some cases you may add / remove selectables during a selection.
Especially when it comes to scrolling.
In this case make sure to call selection.resolveSelectables()
every time you add / remove a selectable so that viselect is aware of the change.
Event properties
Every event comes with the following properties:
{
selection: SelectionArea
event: TouchEvent | MouseEvent | null
store: {
touched: Element[]
selected: Element[]
stored: Element[]
changed: {
added: Element[]
removed: Element[]
}
}
}
Common recipes can be found under recipes.