npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

drag-on-drop

v3.6.1

Published

Accessible drag and drop list reorder

Downloads

10,319

Readme

Dragon Drop

CircleCI

Keyboard/assistive technology accessible drag-and-drop reorder list.

Demo

http://schne324.github.io/dragon-drop/demo/

Enter the dragon...

For an in-depth look at dragon drop see the smashing magazine article on dragon drop

Installation

npm

$ npm install drag-on-drop

bower

$ bower install drag-on-drop

Usage

Browserify/Webpack

import DragonDrop from 'drag-on-drop';

const dragon = new DragonDrop(container, options);

In the browser

const DragonDrop = window.DragonDrop;
const dragon = new DragonDrop(container, options);

React

Although a DragonDrop react component doesn't exist (yet), it can be used with react:

class App extends Component {
  componentDidMount() {
    this.setState({
      dragonDrop: new DragonDrop(this.dragon)
    });
  }

  componentDidUpdate() {
    const { dragonDrop } = this.state;
    // this public method allows dragon drop to
    // reassess the updated items and handles
    dragonDrop.initElements(this.dragon);
  }

  render() {
    return (
      <ul className='dragon' ref={el => this.dragon = el}>
        <li>
          <button type='button' aria-label='Reorder' />
          <span>Item 1</span>
        </li>
        <li>
          <button type='button' aria-label='Reorder' />
          <span>Item 2</span>
        </li>
      </ul>
    );
  }
}

Full example

NOTE usage with react is not exactly ideal because DragonDrop uses normal DOM events not picked up by react (react doesn't know about the reordering).

CDN (unpkg)

https://unpkg.com/drag-on-drop

API

new DragonDrop(container, [options])

container HTMLElement|Array (required)

Either a single container element or an array of container elements.

options Object (optional)

item String

The selector for the drag items (qualified within container). Defaults to

'li'
handle String

The selector for the keyboard handle (qualified within the container and the selector provided for item). If set to false, the entire item will be used as the handle. Defaults to

'button'
activeClass String

The class to be added to the item being dragged. Defaults to

'dragon-active'
inactiveClass String

The class to be added to all of the other items when an item is being dragged. Defaults

'dragon-inactive'
nested Boolean

Set to true if nested lists are being used (click and keydown events will not bubble up (e.stopPropagation() will be applied)). For nested lists, you MUST pass DragonDrop an array of containers as the 1st parameter (see example below).

NOTE: there is a 99% chance that you'll need to use :scope selectors to target only a given list's items (because dragon drop would otherwise include the sub list's items for example). Using :scope selectors will allow you to target direct descendant children (example: :scope > li).

const lists = Array.from(document.querySelectorAll('.dragon-list'));
const dragons = new DragonDrop(lists, {
  nested: true,
  handle: false,
  item: ':scope > li' // IMPORTANT! a selector that targets only a single list's items
});
const [ topLevel, sublist1, sublist2 ] = dragons;

topLevel.on('grabbed', () => console.log('top-most container item grabbed'));
sublist1.on('grabbed', () => console.log('sublist 1 item grabbed'));
sublist2.on('grabbed', () => console.log('sublist 1 item grabbed'));
dragulaOptions Object

An options object passed through to dragula.

NOTE: dragulaOptions.moves will be ignored given a DragonDrop instance with nested: false and a truthy handle

NOTE: dragulaOptions.moves AND dragulaOptions.accepts will be ignored given a DragonDrop instance with nested: true

announcement Object

The live region announcement configuration object containing the following properties:

grabbed Function

The function called when an item is picked up. The currently grabbed element along with an array of all items are passed as arguments respectively. The function should return a string of text to be announced in the live region. Defaults to

el => `Item ${el.innerText} grabbed`
dropped Function

The function called when an item is dropped. The newly dropped item along with an array of all items are passed as arguments respectively. The function should return a string of text to be announced in the live region. Defaults to

el => `Item ${el.innerText} dropped`
reorder Function

The function called when the list has been reordered. The newly dropped item along with an array of items are passed as arguments respectively. The function should return a string of text to be announced in the live region. Defaults to

(el, items) => {
  const pos = items.indexOf(el) + 1;
  const text = el.innerText;
  return `The list has been reordered, ${text} is now item ${pos} of ${items.length}`;
}
cancel Function

The function called when the reorder is cancelled (via ESC). No arguments passed in. Defaults to

() => 'Reordering cancelled'
liveRegion Object

Attributes that can be overridden in on the live region:

ariaLive string

Optional ariaLive attribute to be passed to the live region. Valid values are "off", "polite", or "assertive". Default is "assertive".

ariaRelevant string

Optional ariaRelevant attribute to be passed to the live region. Valid values are "additions", "removals", "text", and "all". Default is "additions".

ariaAtomic boolean

Optional ariaAtomic attribute to be passed to the live region. Default is "true".

Properties

const dragonDrop = new DragonDrop(container);

dragonDrop.items Array

An array of each of the sortable item element references.

dragonDrop.handles Array

An array of each of the handle item element references. If instance doesn't have handles, this will be identical to dragonDrop.items.

dragonDrop.dragula

A direct handle on the dragula instance created by dragonDrop

Example with options

const list = document.getElementById('dragon-list');
const dragonDrop = new DragonDrop(list, {
  item: 'li',
  handle: '.handle',
  announcement: {
    grabbed: el => `The dragon has grabbed ${el.innerText}`,
    dropped: el => `The dragon has dropped ${el.innerText}`,
    reorder: (el, items) => {
      const pos = items.indexOf(el) + 1;
      const text = el.innerText;
      return `The dragon's list has been reordered, ${text} is now item ${pos} of ${items.length}`;
    },
    cancel: 'The dragon cancelled the reorder'
  }
});

Events

Dragon drop emit events when important stuff happens.

dragonDrop.on('grabbed', callback)

Fires when an item is grabbed (with keyboard or mouse). The callback is passed the container along with the grabbed item.

dragonDrop.on('dropped', callback)

Fires when an item is dropped (with keyboard or mouse). The callback is passed the container and the grabbed item.

dragonDrop.on('reorder', callback)

Fires when a list is reordered. The callback is passed the container along with the item.

dragonDrop.on('cancel', callback)

Fires when a user cancels reordering with the escape key. The callback is passed the keydown event that triggered the cancel.

Example use of events

dragonDrop
  .on('grabbed', (container, item) => console.log(`Item ${item.innerText} grabbed`))
  .on('dropped', (container, item) => console.log(`Item ${item.innerText} dropped`))
  .on('reorder', (container, item) => console.log(`Reorder: ${item.innerText} has moved`))
  .on('cancel', (e) => {
    console.log('Reordering cancelled');
    e.preventDefault();
  });

NOTE for mouse drag/drop event hooks the dragula property is exposed for dragula's events

dragonDrop.dragula.on('drop', ...);

Methods

dragonDrop.initElements(container)

Reinitialises the list, so that newly added items can be dragged. You can do this automatically with a MutationObserver:

const observer = new MutationObserver(() => dragonDrop.initElements(container));
observer.observe(container, {childList: true});

Debugging

Set the following localStorage option to debug dragonDrop

localStorage.debug = 'drag-on-drop:*';

Notes on accessibility

There are certain things that are left up to the discretion of the implementer. This is to keep DragonDrop less opinionated on some of the gray areas of a11y. The demos show a few different approaches on associating help text with DragonDrop:

  1. Recommended aria-describedby on each control (item, or if applicable, handle). This is the safest/test approach because it guarantees that AT users will receive the instructions. Demo of this approach
  2. Recommended aria-labelledby on the container/list element. With this approach, where supported, will announce the instructions whenever the AT users enters the list (which is less verbose than the above). Demo of this approach
  3. Not recommendedaria-describedby on the container/list element. This approach, where supported, will only announce the instructions if the screen reader user traverses to the actual list element. Demo of this approach

For more information regarding accessibility you can read an accessibility review of dragon drop initiated by Drupal.

Thanks!

A special thanks to Aaron Pearlman for the logo.

Another special thanks to contributors/maintainers of dragula which is used for all of the mouse behavior/interaction for dragon drop!