Skip to content

Latest commit

 

History

History
276 lines (185 loc) · 12 KB

README.md

File metadata and controls

276 lines (185 loc) · 12 KB

The DragSelect logo: a selection symbol, a hand, a drop symbol and a mouse within a selection square.

Project-Page | Documentation | Github | NPM | Licenses

Build Status gzip size npm downloads count No Dependency Contributors Welcome Sponsors Welcome

DragSelect GitHub release

easily add a selection algorithm to your application/website.

The documentation is being migrated to https://dragselect.com/. Find the most up to date documentation there.

TOC

Project Page: Demo & Info

Key-Features

  • No dependencies No Dependency
  • Hyper customizable
  • Replicates operating system drag-selection in the browser
  • Accessibility (a11y)
  • Use modifier keys to make multiple independent selections
  • Select, Drag and Drop also also via keyboard
  • Supports all major browsers
  • Lightweight, only gzip size
  • Popular: npm downloads count on npm
  • DragSelect was written with Performance in mind (can easily select >15.000 Elements)
  • Supports SVG
  • Supports mobile (touch interaction)
  • Free & open source
  • Easy to use

demo-gif

Why?

Because apparently there was nothing that does not require jquery out there.
This is better than https://jqueryui.com/selectable/ or https://jqueryui.com/draggable/ and has no dependencies. It is used in multiple professional rich interface applications, i.e. to have a file management system. The user can select files to organize them and change their metadata, with this plugin our users could select multiple files and perform batch/bulk-operations (applying changes to multiple files at once). Another example is a huge, graphical cloud hosting manager with millions of active users. Users can select multiple servers, storages, etc. on an art-board to perform multi-operations, re-organize them, move them on the UI or batch-delete. We’re running it since January 18' it’s super helpful and very stable, let’s keep it that way. I can easily think of dozens other use-cases. I’m really keen to know how you use it in your projects, please let us know.

Supporters

Please donate to support the countless hours of hard work & support. Especially if your company makes money, then there is no excuse. Thank you :)

If you're too poor or broke you can still support us with your time instead by contributing to the code!

Thanks To:

LambdaTest

LambdaTest

LambdaTest is a Next-Generation Mobile App and Cross Browser Testing Cloud. They support this open source projects by providing us with a free account and with a generous donation!

BrowserStack

Browserstack

BrowserStack is a service for cross-browser testing. They support this open source projects by providing us with a free account!

DigitalOcean

DigitalOcean

DigitalOcean is a cloud hosting service. They support this open source projects by providing us with free credits!

You?

You?

Show your appreciation and support with a donation! Direct Donation to DragSelect (via Bitcoin: 1LdweSpjgSeJC8XxX3swrohBMBLUzg6cmC). Or sponsor via GitHub Sponsors or Get in touch.

Donations are distributed with all project contributors proportionally to their involvement. We are grateful for any amount: we have more than npm downloads count, imagine how much we'd have if everyone would have had donated only 1$ 🤩 (unfortunately this is just a dream). If you donate, we can display your logo here if you want, which will give you infinite fame, fortune and help you recruit great talent.

Installation

Read the Getting Started.

NPM

npm install --save dragselect

Yarn

yarn add dragselect

Global

You can still download the file (minified) and add it to your document:

<script src="https://unpkg.com/dragselect@latest/dist/ds.min.js"></script>

Note: if you are using <script type=module you can use the DragSelect.esm.js or ds.esm.min.js files as they include export default DragSelect

We don’t recommend the direct linking for production set-up. Please use npm if you can.

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

Of course you can also just include the code within your code and bundle it to save a request.

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

Usage

Now in your JavaScript you can simply pass elements to the function like so:

Simple

Read the Simple Usage Guide

The simplest possible usage.
Choose which elements can be selected:

new DragSelect({
  selectables: document.getElementsByClassName("selectable-nodes"),
});

Find a live example in the Guide

Within a Scroll-Able Area

Read the Area Guide

Here the selection is constrained. You can only use the selection/drag inside of the area container:

new DragSelect({
  selectables: document.getElementsByClassName("selectable-nodes"),
  area: document.getElementById("area"),
});

Find a live example in the Area Guide

With DropZones

Read the DropZones Guide where you’ll also find a live example.

Extended

All options are optional. You could also just initiate the Dragselect by new DragSelect({}); without any option.

Find all possible properties and methods in the docs

Hint: you can also use the "shift", "ctrl" or "command" key to make multiple independent selections.

React

Read the React Guide

Mobile/Touch usage

Read the Mobile Touch Guide

Accessibility (a11y)

DragSelect is accessible by default:

TLDR;
=> Your selectables should be buttons: <button type="button"></button>.
=> ArrowKeys are used for keyboard dragging.

Read the Accessibility Guide

Use Your Own Drag & Drop

Read the Custom Drag and Drop Guide

Constructor Properties (Settings)

DragSelect is hyper customizable. Note, all properties are optional.

Read the Settings API docs

Moreover any setting can also be updated or added after the initialization, see post-initialization setting updates.

Post-Initialization Setting-Updates

Any setting can be updated/added after initialization by using the setSettings method. Here is an example updating the area and the selectables:

const ds = new DragSelect({})
ds.setSettings({
  selectables: document.getElementsByClassName('selectable-nodes'),
  area: document.getElementById('area')
})

Event Callbacks

Read the Events API docs

Event Callbacks are used like this:

ds.subscribe('<event_name>', (callback_object) => {})

For all available callback event_names and their respective callback_object, please read the Events API docs

Methods

Read the Methods API docs

CSS Classes

Read the CSS Classes API docs

Have Fun!

Creating and maintaining useful tools is a lot of work. So don’t forget to give this repository a star if you find it useful. Star this repo, tell all your friends and start contributing and/or donating 1$ to keep it running. Thank you :)

Typewriter Gif

http://dragselect.com/ | documentation