____                   _____      __          __ 
   / __ \_________ _____ _/ ___/___  / /__  _____/ /_
  / / / / ___/ __ `/ __ `/\__ \/ _ \/ / _ \/ ___/ __/
 / /_/ / /  / /_/ / /_/ /___/ /  __/ /  __/ /__/ /_  
/_____/_/   \__,_/\__, //____/\___/_/\___/\___/\__/  
                 /____/                              
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

DragSelect supports `module.exports`, `AMD Modules` with `define` and has a fallback to global namespace for maximum out of the box support.

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']
  autoScrollSpeed: 3,  // Speed in which the area scrolls while selecting (if available). Unit is pixel per movement. Set to 0.0001 to disable autoscrolling. Default = 1
  onDragStart: function(element) {}, // fired when the user clicks in the area. This callback gets the event object. Executed after DragSelect function code ran, befor the setup of event listeners.
  onDragMove: function(element) {}, // fired when the user drags. This callback gets the event object. Executed before DragSelect function code ran, after getting the current mouse position.
  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 algorithm 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.break();  // used in callbacks to disable the execution of the upcoming code. It will not teardown the functionality.
ds.stop();  // will teardown/stop the whole functionality
ds.start();  // reset the functionality after a teardown
// and many more, see "methods" section in documentation

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 (unfortunately this does not work in firefox for now since FF doesn’t add the modifier key in the event object when using the keyboard). 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']
autoScrollSpeed integerOPTIONAL. Speed in which the area scrolls while selecting (if available). Unit is pixel per movement. Set to 0.0001 to disable autoscrolling. Default = 1
onDragStart functionOPTIONAL. Fired when the user clicks in the area. This callback gets the event object. Executed after DragSelect function code ran, befor the setup of event listeners
onDragMove functionOPTIONAL. Fired when the user drags. This callback gets the event object. Executed before DragSelect function code ran, after getting the current mouse position
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
break/used in callbacks to disable the execution of the upcoming code. It will not teardown the functionality
getSelection/returns all currently selected nodes
addSelectionnodes, boolean, booleanadds one or multiple elements to the selection. If boolean is set to true: callback will be called afterwards. By default, it checks if all elements ere alos in the list of selectables and adds them if not (can be turned off by setting the last boolean to true)
removeSelectionnodes, boolean, booleanremoves one or multiple elements to the selection. If boolean is set to true: callback will be called afterwards. If last bolean is set to true, it also removes them from the possible selectable nodes if they were.
toggleSelectionnodes, boolean, booleantoggles one or multiple elements to the selection. If element is not in selection it will be added, if it is already selected, it will be removed. If boolean is set to true: callback will be called afterward. If last boolean is set to true, it also removes selected elements from possible selectable nodes & doesn’t add them to selectables if they are not.
setSelectionnodes, boolean, booleansets the selection to one or multiple elements. If boolean is set to true: callback will be called afterwards. By default, it checks if all elements ere alos in the list of selectables and adds them if not (can be turned off by setting the last boolean to true)
clearSelectionnodes, booleanremove all elements from the selection. If boolean is set to true: callback will be called afterwards
addSelectablesnodes, booleanadds elements that can be selected. Don’t worry, a smart algorithm 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.
getInitialCursorPosition/returns the x, y coordinates the cursor had when the first click was registered
getCurrentCursorPosition/returns last registered x, y coordinates of the cursor
getCursorPositionDifferencebooleanreturns object with the x, y difference between the initial and the last cursor position. If the argument is set to true, it will instead return the x, y difference to the previous selection
getCursorPosclick-event, nodes, booleanreturns the cursor x, y coordinates based on a click event object. The click event object is required. By default, takes scroll and area into consideration. Area is this.area by default and can be fully ignored by setting the second argument explicitely to false. Scroll can be ignored by setting the third argument to true.

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!