____                   _____      __          __ 
   / __ \_________ _____ _/ ___/___  / /__  _____/ /_
  / / / / ___/ __ `/ __ `/\__ \/ _ \/ / _ \/ ___/ __/
 / /_/ / /  / /_/ / /_/ /___/ /  __/ /  __/ /__/ /_  
/_____/_/   \__,_/\__, //____/\___/_/\___/\___/\__/  
                 /____/                              
Download

Browser Support & Accessibility

DragSelect was successfully tested on all modern browsers and a wide range of legacy browsers, it even works perfectly on ie9. Also, DragSelect is accessible by default.

Ease of use

Your time matters, so DragSelect is super quick and easy to use. If you know the basics of javascript you're ready to rock. Also, no dependencies.

Lightweight

You want your website to be loaded as fast as possible. So DragSelect only weights ~2KB gzipped which is an average of 0,00004s loadtime. You name it – it's nothing. Also, no dependencies.

Free

DragSelect is published under the MIT license and completely free to use. Oh and it's Open Source as well, so you can make it even better.

animated typewriter gif

Documentation

1. Installation

Regular:

Download DragSelect (minified) and add it to your document:

<script src="https://thibaultjanbeyer.github.io/DragSelect/ds.min.js"></script>

That's it, you're ready to rock!

Of course you can also just include the code within your code to save a request

With NPM:
npm install --save-dev dragselect
With Bower:
bower install --save-dev dragselect

2. Simple Usage

The simplest possible usage:

See the Pen prpwYG by Thibault Jan Beyer (@ThibaultJanBeyer) on CodePen.

You can also use the "shift", "ctrl" or "command" key to make multiple independent selections. Try it out!

2b. Widthin a scrollable area

Here the selection is constrained. You can only use the selection inside of the container with the red border:

See the Pen DragSelect with Scrollable AREA by Thibault Jan Beyer (@ThibaultJanBeyer) on CodePen.

2c. Extended

All options are optional. You could also just initiate the Dragselect by `new DragSelect();` without any option. If you add the function to a variable you get full controll over all its functions:
var ds = new DragSelect({
  selectables: document.getElementsByClassName('selectable-nodes'), // node/nodes that can be selected. This is also optional, you could just add them later with .addSelectables.
  selector: document.getElementById('rectangle'), // draggable element. By default one will be created.
  area: document.getElementById('area'), // area in which you can drag. If not provided it will be the whole document.
  customStyles: false,  // If set to true, no styles (except for position absolute) will be applied by default.
  multiSelectKeys: ['ctrlKey', 'shiftKey', 'metaKey'],  // special keys that allow multiselection. These key will allow the user add more elements to the selection instead of clearing the selection. The only possible values are keys that are provided via the event object. So far: <kbd>ctrlKey</kbd>, <kbd>shiftKey</kbd>, <kbd>metaKey</kbd> and <kbd>altKey</kbd>. Provide an empty array [] if you want to turn off the funcionality. Default: ['ctrlKey', 'shiftKey', 'metaKey']
  onElementSelect: function(element) {}, // fired every time an element is selected. (element) = just selected node
  onElementUnselect: function(element) {}, // fired every time an element is de-selected. (element) = just de-selected node.
  callback: function(elements) {} // fired once the user releases the mouse. (elements) = selected nodes.
});

// if you add the function to a variable like we did, you have access to all its functions
// and can now use start() and stop() like so:
ds.getSelection();  // returns all currently selected nodes
ds.addSelectables(document.getElementsByClassName('selectable-node'));  // adds elements that can be selected. Intelligent algorythm never adds elements twice.
ds.removeSelectables(document.getElementsByClassName('selectable-node'));  // removes elements that can be selected.
ds.getSelectables();  // returns array of nodes that can be selected.
ds.stop();  // will teardown/stop the whole functionality
ds.start();  // reset the functionality after a teardown

2d. Accessibility (a11y)

DragSelect is accessibly by default.

TLDR; => Your selectables should be buttons:

<button type="button"></button>

Obviously, keyboard users won’t get the full visual experience but it works similarely to the OS default behaviour. You can select items using the default select keys (usually space or enter) and also multiselect when using a modifier key at the same time. There is one little thing you have to do tho’: the selectables have to be pressable (clickable)! To achieve this, they should be buttons: . Try it out:

See the Pen DragSelect by Thibault Jan Beyer (@ThibaultJanBeyer) on CodePen.

3. Properties:

Reference:
PropertyTypeUse
selectables NodesOPTIONAL. The elements that can be selected
selector single DOM element (node)OPTIONAL. The square that will draw the selection. Autocreated by default
area single DOM element (node)OPTIONAL. The square in which you are able to select
customStyles booleanOPTIONAL. If true, no styles will be automatically applied (except position: absolute). Default: false
multiSelectKeys arrayOPTIONAL. These key will allow the user add more elements to the selection instead of clearing the selection. The only possible values are keys that are provided via the event object. So far: ctrlKey, shiftKey, metaKey and altKey. Provide an empty array [] if you want to turn off the funcionality. Default: ['ctrlKey', 'shiftKey', 'metaKey']
onElementSelect functionOPTIONAL. Fired every time an element is selected. This callback gets a property which is the selected node
onElementUnselect functionOPTIONAL. Fired every time an element is de-selected. This callback gets a property which is the de-selected node
callback functionOPTIONAL. Callback function that gets fired when the selection is released. This callback gets a property which is an array that holds all selected nodes
Info: use method: ".getSelection()" to returns all currently selected nodes.

4. Methods

When the function is saved into a variable (var foo = new DragSelect({...})) you have access to all its inner functions. There are way more than listed here. Here are just the most usable:

Reference:
MethodPropertiesUse
stop/will teardown/stop the whole functionality
start/reset the functionality after a teardown
getSelection/returns all currently selected nodes
addSelectablesnodes, booleanadds elements that can be selected. Don’t worry, a smart algorythm makes sure that nodes are never added twice. If boolean is set to true: elements will also be added to current selection
removeSelectablesnodes, booleanremove elements that can be selected. If boolean is set to true: elements will also be removed from current selection.
getSelectablesnodesreturns array with all nodes that can be selected.

5. Classes

Reference:
.ds-hoveron elements that are currently hovered
.ds-selectedon elements that are selected
.ds-selectoron the selector element
.ds-selectableon elements that can be selected

Have Fun!