dragula

:ok_hand: Drag and drop so simple it hurts

21,948

1,966

21,948

158

View on GitHub View on NPM

Top Related Projects

Sortable

29,570

Reorderable drag-and-drop lists for modern browsers and touch devices. No jQuery or framework required.

react-beautiful-dnd

33,147

Beautiful and accessible drag and drop for lists with React

react-sortable-hoc

10,774

A set of higher-order components to turn any list into an animated, accessible and touch-friendly sortable list✌️

muuri

10,773

Infinite responsive, sortable, filterable and draggable layouts

moveable

9,916

Moveable! Draggable! Resizable! Scalable! Rotatable! Warpable! Pinchable! Groupable! Snappable!

Quick Overview

Dragula is a lightweight JavaScript library for drag and drop functionality. It provides a simple and flexible way to implement drag and drop features in web applications, with support for both mouse and touch events. Dragula works across browsers and devices, making it a versatile choice for developers.

Pros

Easy to use with minimal setup required
Lightweight and performant
Customizable with various options and events
Works well with modern JavaScript frameworks

Cons

Limited built-in styling options
May require additional work for complex drag and drop scenarios
Documentation could be more comprehensive
Not actively maintained (last update was in 2019)

Code Examples

Basic usage:

import dragula from 'dragula';

const container = document.querySelector('#container');
const drake = dragula([container]);

This code sets up basic drag and drop functionality for elements within the specified container.

Custom moves:

const drake = dragula([container], {
  moves: function (el, source, handle, sibling) {
    return el.classList.contains('draggable');
  }
});

This example demonstrates how to customize which elements can be dragged by checking for a specific CSS class.

Handling events:

drake.on('drop', (el, target, source, sibling) => {
  console.log('Element dropped!');
  // Perform actions after drop
});

This code shows how to listen for and respond to drag and drop events.

Getting Started

Install Dragula:
```
npm install dragula
```

Import and use in your JavaScript:

import dragula from 'dragula';

const containers = document.querySelectorAll('.container');
const drake = dragula(Array.from(containers));

drake.on('drop', (el, target, source, sibling) => {
  console.log('Element dropped!');
  // Your custom logic here
});

Add some basic CSS (optional):

.gu-mirror {
  position: fixed !important;
  margin: 0 !important;
  z-index: 9999 !important;
  opacity: 0.8;
}

This setup provides a basic implementation of drag and drop functionality using Dragula. Adjust the selectors and event handling as needed for your specific use case.

Competitor Comparisons

Sortable

29,570

Reorderable drag-and-drop lists for modern browsers and touch devices. No jQuery or framework required.

Pros of Sortable

More feature-rich, offering advanced sorting capabilities like multi-list sorting and nested lists
Better performance for large lists and complex sorting scenarios
Extensive API and configuration options for fine-tuned control

Cons of Sortable

Larger file size and potentially more complex setup compared to Dragula
Steeper learning curve due to more configuration options and features

Code Comparison

Dragula:

dragula([document.getElementById('left'), document.getElementById('right')])
  .on('drag', function (el) {
    el.className += ' is-moving';
  });

Sortable:

new Sortable(document.getElementById('list'), {
  animation: 150,
  ghostClass: 'blue-background-class',
  onEnd: function (evt) {
    var itemEl = evt.item;
    console.log(itemEl);
  }
});

Both libraries offer straightforward implementation, but Sortable provides more configuration options out of the box. Dragula's API is simpler and more focused on drag-and-drop functionality, while Sortable offers additional features for complex sorting scenarios. The choice between the two depends on the specific requirements of your project, with Dragula being suitable for simpler drag-and-drop needs and Sortable excelling in more complex sorting applications.

react-beautiful-dnd

33,147

Beautiful and accessible drag and drop for lists with React

Pros of react-beautiful-dnd

Specifically designed for React applications, offering seamless integration
Provides a more accessible drag and drop experience with keyboard support
Offers advanced features like multi-drag and auto-scrolling

Cons of react-beautiful-dnd

Limited to React applications, not suitable for vanilla JavaScript projects
Has a steeper learning curve due to its React-specific API
Larger bundle size compared to Dragula

Code Comparison

react-beautiful-dnd:

import { DragDropContext, Droppable, Draggable } from 'react-beautiful-dnd';

<DragDropContext onDragEnd={onDragEnd}>
  <Droppable droppableId="list">
    {(provided) => (
      <ul {...provided.droppableProps} ref={provided.innerRef}>
        {items.map((item, index) => (
          <Draggable key={item.id} draggableId={item.id} index={index}>
            {(provided) => (
              <li ref={provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps}>
                {item.content}
              </li>
            )}
          </Draggable>
        ))}
        {provided.placeholder}
      </ul>
    )}
  </Droppable>
</DragDropContext>

Dragula:

import dragula from 'dragula';

dragula([document.querySelector('#left'), document.querySelector('#right')])
  .on('drag', function(el) {
    el.className += ' is-moving';
  })
  .on('drop', function(el) {
    el.className = el.className.replace('is-moving', '');
  });

react-sortable-hoc

10,774

A set of higher-order components to turn any list into an animated, accessible and touch-friendly sortable list✌️

Pros of react-sortable-hoc

Specifically designed for React applications, providing seamless integration
Supports virtualized lists, enabling efficient rendering of large datasets
Offers more customization options and flexibility for complex sorting scenarios

Cons of react-sortable-hoc

Steeper learning curve due to its React-specific implementation
May have a larger bundle size compared to Dragula's lightweight approach
Limited to React applications, whereas Dragula is framework-agnostic

Code Comparison

react-sortable-hoc:

import { SortableContainer, SortableElement } from 'react-sortable-hoc';

const SortableItem = SortableElement(({value}) => <li>{value}</li>);
const SortableList = SortableContainer(({items}) => {
  return (
    <ul>
      {items.map((value, index) => (
        <SortableItem key={`item-${index}`} index={index} value={value} />
      ))}
    </ul>
  );
});

Dragula:

import dragula from 'dragula';

dragula([document.querySelector('#left-container'), document.querySelector('#right-container')]);

Both libraries offer drag-and-drop functionality, but react-sortable-hoc is more tightly integrated with React's component model, while Dragula provides a simpler, more generic approach that can be used with any framework or vanilla JavaScript.

muuri

10,773

Infinite responsive, sortable, filterable and draggable layouts

Pros of Muuri

More feature-rich, offering advanced grid layouts and responsive design
Supports both drag-and-drop and sorting functionalities
Better performance for large-scale applications with many elements

Cons of Muuri

Steeper learning curve due to more complex API
Larger file size, which may impact load times for smaller projects
Less frequently updated compared to Dragula

Code Comparison

Muuri:

const grid = new Muuri('.grid', {
  dragEnabled: true,
  layoutOnInit: false
});
grid.layout();

Dragula:

dragula([document.querySelector('.container')], {
  direction: 'vertical'
});

Summary

Muuri offers more advanced features and better performance for complex layouts, while Dragula provides a simpler API for basic drag-and-drop functionality. Muuri is ideal for larger projects requiring grid layouts, while Dragula is better suited for simpler use cases and smaller applications. The choice between the two depends on the specific requirements of your project and the level of complexity you're willing to manage.

moveable

9,916

Moveable! Draggable! Resizable! Scalable! Rotatable! Warpable! Pinchable! Groupable! Snappable!

Pros of Moveable

More comprehensive feature set, including resizing, rotating, and snapping
Supports multiple frameworks (React, Vue, Angular) out of the box
Offers more customization options and advanced interactions

Cons of Moveable

Steeper learning curve due to its extensive API and options
Larger bundle size, which may impact performance for simpler use cases
More complex setup process compared to Dragula's simplicity

Code Comparison

Dragula:

dragula([document.getElementById('left'), document.getElementById('right')])
  .on('drag', function (el) {
    el.className += ' is-moving';
  });

Moveable:

const moveable = new Moveable(document.body, {
  target: document.querySelector(".target"),
  draggable: true,
  resizable: true,
  rotatable: true
});
moveable.on("drag", ({ target, transform }) => {
  target.style.transform = transform;
});

Summary

Moveable offers a more feature-rich and versatile solution for creating interactive elements, supporting various transformations and frameworks. However, this comes at the cost of increased complexity and a larger footprint. Dragula, on the other hand, provides a simpler and more lightweight approach focused primarily on drag-and-drop functionality. The choice between the two depends on the specific requirements of your project and the level of customization needed.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Drag and drop so simple it hurts

Browser support includes every sane browser and IE7+. _{(Granted you polyfill the functional Array methods in ES5)}

Framework support includes vanilla JavaScript, Angular, and React.

Official Angular bridge for dragula (demo)
Official Angular 2 bridge for dragula (demo)
Official React bridge for dragula (demo)

Demo

Try out the demo!

Inspiration

Have you ever wanted a drag and drop library that just works? That doesn't just depend on bloated frameworks, that has great support? That actually understands where to place the elements when they are dropped? That doesn't need you to do a zillion things to get it to work? Well, so did I!

Features

Super easy to set up
No bloated dependencies
Figures out sort order on its own
A shadow where the item would be dropped offers visual feedback
Touch events!
Seamlessly handles clicks without any configuration

Install

You can get it on npm.

npm install dragula --save

Or a CDN.

<script src='https://cdnjs.cloudflare.com/ajax/libs/dragula/$VERSION/dragula.min.js'></script>

If you're not using either package manager, you can use dragula by downloading the files in the dist folder. We strongly suggest using npm, though.

Including the JavaScript

There's a caveat to dragula. You shouldn't include it in the <head> of your web applications. It's bad practice to place scripts in the <head>, and as such dragula makes no effort to support this use case.

Place dragula in the <body>, instead.

Including the CSS!

There's a few CSS styles you need to incorporate in order for dragula to work as expected.

You can add them by including dist/dragula.css or dist/dragula.min.css in your document. If you're using Stylus, you can include the styles using the directive below.

@import 'node_modules/dragula/dragula'

Usage

Dragula provides the easiest possible API to make drag and drop a breeze in your applications.

`dragula(containers?, options?)`

By default, dragula will allow the user to drag an element in any of the containers and drop it in any other container in the list. If the element is dropped anywhere that's not one of the containers, the event will be gracefully cancelled according to the revertOnSpill and removeOnSpill options.

Note that dragging is only triggered on left clicks, and only if no meta keys are pressed.

The example below allows the user to drag elements from left into right, and from right into left.

dragula([document.querySelector('#left'), document.querySelector('#right')]);

You can also provide an options object. Here's an overview of the default values.

dragula(containers, {
  isContainer: function (el) {
    return false; // only elements in drake.containers will be taken into account
  },
  moves: function (el, source, handle, sibling) {
    return true; // elements are always draggable by default
  },
  accepts: function (el, target, source, sibling) {
    return true; // elements can be dropped in any of the `containers` by default
  },
  invalid: function (el, handle) {
    return false; // don't prevent any drags from initiating by default
  },
  direction: 'vertical',             // Y axis is considered when determining where an element would be dropped
  copy: false,                       // elements are moved by default, not copied
  copySortSource: false,             // elements in copy-source containers can be reordered
  revertOnSpill: false,              // spilling will put the element back where it was dragged from, if this is true
  removeOnSpill: false,              // spilling will `.remove` the element, if this is true
  mirrorContainer: document.body,    // set the element that gets mirror elements appended
  ignoreInputTextSelection: true,     // allows users to select input text, see details below
  slideFactorX: 0,               // allows users to select the amount of movement on the X axis before it is considered a drag instead of a click
  slideFactorY: 0,               // allows users to select the amount of movement on the Y axis before it is considered a drag instead of a click
});

You can omit the containers argument and add containers dynamically later on.

var drake = dragula({
  copy: true
});
drake.containers.push(container);

You can also set the containers from the options object.

var drake = dragula({ containers: containers });

And you could also not set any arguments, which defaults to a drake without containers and with the default options.

var drake = dragula();

The options are detailed below.

`options.containers`

Setting this option is effectively the same as passing the containers in the first argument to dragula(containers, options).

`options.isContainer`

Besides the containers that you pass to dragula, or the containers you dynamically push or unshift from drake.containers, you can also use this method to specify any sort of logic that defines what is a container for this particular drake instance.

The example below dynamically treats all DOM elements with a CSS class of dragula-container as dragula containers for this drake.

var drake = dragula({
  isContainer: function (el) {
    return el.classList.contains('dragula-container');
  }
});

`options.moves`

You can define a moves method which will be invoked with (el, source, handle, sibling) whenever an element is clicked. If this method returns false, a drag event won't begin, and the event won't be prevented either. The handle element will be the original click target, which comes in handy to test if that element is an expected "drag handle".

`options.accepts`

You can set accepts to a method with the following signature: (el, target, source, sibling). It'll be called to make sure that an element el, that came from container source, can be dropped on container target before a sibling element. The sibling can be null, which would mean that the element would be placed as the last element in the container. Note that if options.copy is set to true, el will be set to the copy, instead of the originally dragged element.

Also note that the position where a drag starts is always going to be a valid place where to drop the element, even if accepts returned false for all cases.

`options.copy`

If copy is set to true (or a method that returns true), items will be copied rather than moved. This implies the following differences:

Event	Move	Copy
`drag`	Element will be concealed from `source`	Nothing happens
`drop`	Element will be moved into `target`	Element will be cloned into `target`
`remove`	Element will be removed from DOM	Nothing happens
`cancel`	Element will stay in `source`	Nothing happens

If a method is passed, it'll be called whenever an element starts being dragged in order to decide whether it should follow copy behavior or not. Consider the following example.

copy: function (el, source) {
  return el.className === 'you-may-copy-us';
}

`options.copySortSource`

If copy is set to true (or a method that returns true) and copySortSource is true as well, users will be able to sort elements in copy-source containers.

copy: true,
copySortSource: true

`options.revertOnSpill`

By default, spilling an element outside of any containers will move the element back to the drop position previewed by the feedback shadow. Setting revertOnSpill to true will ensure elements dropped outside of any approved containers are moved back to the source element where the drag event began, rather than stay at the drop position previewed by the feedback shadow.

`options.removeOnSpill`

By default, spilling an element outside of any containers will move the element back to the drop position previewed by the feedback shadow. Setting removeOnSpill to true will ensure elements dropped outside of any approved containers are removed from the DOM. Note that remove events won't fire if copy is set to true.

`options.direction`

When an element is dropped onto a container, it'll be placed near the point where the mouse was released. If the direction is 'vertical', the default value, the Y axis will be considered. Otherwise, if the direction is 'horizontal', the X axis will be considered.

`options.invalid`

You can provide an invalid method with a (el, handle) signature. This method should return true for elements that shouldn't trigger a drag. The handle argument is the element that was clicked, while el is the item that would be dragged. Here's the default implementation, which doesn't prevent any drags.

function invalidTarget (el, handle) {
  return false;
}

Note that invalid will be invoked on the DOM element that was clicked and every parent up to immediate children of a drake container.

As an example, you could set invalid to return false whenever the clicked element (or any of its parents) is an anchor tag.

invalid: function (el, handle) {
  return el.tagName === 'A';
}

`options.mirrorContainer`

The DOM element where the mirror element displayed while dragging will be appended to. Defaults to document.body.

`options.ignoreInputTextSelection`

When this option is enabled, if the user clicks on an input element the drag won't start until their mouse pointer exits the input. This translates into the user being able to select text in inputs contained inside draggable elements, and still drag the element by moving their mouse outside of the input -- so you get the best of both worlds.

This option is enabled by default. Turn it off by setting it to false. If its disabled your users won't be able to select text in inputs within dragula containers with their mouse.

API

The dragula method returns a tiny object with a concise API. We'll refer to the API returned by dragula as drake.

`drake.containers`

This property contains the collection of containers that was passed to dragula when building this drake instance. You can push more containers and splice old containers at will.

`drake.dragging`

This property will be true whenever an element is being dragged.

`drake.start(item)`

Enter drag mode without a shadow. This method is most useful when providing complementary keyboard shortcuts to an existing drag and drop solution. Even though a shadow won't be created at first, the user will get one as soon as they click on item and start dragging it around. Note that if they click and drag something else, .end will be called before picking up the new item.

`drake.end()`

Gracefully end the drag event as if using the last position marked by the preview shadow as the drop target. The proper cancel or drop event will be fired, depending on whether the item was dropped back where it was originally lifted from (which is essentially a no-op that's treated as a cancel event).

`drake.cancel(revert)`

If an element managed by drake is currently being dragged, this method will gracefully cancel the drag action. You can also pass in revert at the method invocation level, effectively producing the same result as if revertOnSpill was true.

Note that a "cancellation" will result in a cancel event only in the following scenarios.

revertOnSpill is true
Drop target (as previewed by the feedback shadow) is the source container and the item is dropped in the same position where it was originally dragged from

`drake.remove()`

If an element managed by drake is currently being dragged, this method will gracefully remove it from the DOM.

`drake.on` (Events)

The drake is an event emitter. The following events can be tracked using drake.on(type, listener):

Event Name	Listener Arguments	Event Description
`drag`	`el, source`	`el` was lifted from `source`
`dragend`	`el`	Dragging event for `el` ended with either `cancel`, `remove`, or `drop`
`drop`	`el, target, source, sibling`	`el` was dropped into `target` before a `sibling` element, and originally came from `source`
`cancel`	`el, container, source`	`el` was being dragged but it got nowhere and went back into `container`, its last stable parent; `el` originally came from `source`
`remove`	`el, container, source`	`el` was being dragged but it got nowhere and it was removed from the DOM. Its last stable parent was `container`, and originally came from `source`
`shadow`	`el, container, source`	`el`, the visual aid shadow, was moved into `container`. May trigger many times as the position of `el` changes, even within the same `container`; `el` originally came from `source`
`over`	`el, container, source`	`el` is over `container`, and originally came from `source`
`out`	`el, container, source`	`el` was dragged out of `container` or dropped, and originally came from `source`
`cloned`	`clone, original, type`	DOM element `original` was cloned as `clone`, of `type` (`'mirror'` or `'copy'`). Fired for mirror images and when `copy: true`

`drake.canMove(item)`

Returns whether the drake instance can accept drags for a DOM element item. This method returns true when all the conditions outlined below are met, and false otherwise.

item is a child of one of the specified containers for drake
item passes the pertinent invalid checks
item passes a moves check

`drake.destroy()`

Removes all drag and drop events used by dragula to manage drag and drop between the containers. If .destroy is called while an element is being dragged, the drag will be effectively cancelled.

CSS

Dragula uses only four CSS classes. Their purpose is quickly explained below, but you can check dist/dragula.css to see the corresponding CSS rules.

gu-unselectable is added to the mirrorContainer element when dragging. You can use it to style the mirrorContainer while something is being dragged.
gu-transit is added to the source element when its mirror image is dragged. It just adds opacity to it.
gu-mirror is added to the mirror image. It handles fixed positioning and z-index (and removes any prior margins on the element). Note that the mirror image is appended to the mirrorContainer, not to its initial container. Keep that in mind when styling your elements with nested rules, like .list .item { padding: 10px; }.
gu-hide is a helper class to apply display: none to an element.

Contributing

See contributing.markdown for details.

Support

We have a dedicated support channel in Slack. See this issue to get an invite. Support requests won't be handled through the repository.

License

MIT

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of Sortable

Cons of Sortable

Code Comparison

Pros of react-beautiful-dnd

Cons of react-beautiful-dnd

Code Comparison

Pros of react-sortable-hoc

Cons of react-sortable-hoc

Code Comparison

Pros of Muuri

Cons of Muuri

Code Comparison

Summary

Pros of Moveable

Cons of Moveable

Code Comparison

Summary

Convert designs to code with AI

README

Demo

Inspiration

Features

Install

Including the JavaScript

Including the CSS!

Usage

dragula(containers?, options?)

options.containers

options.isContainer

options.moves

options.accepts

options.copy

options.copySortSource

options.revertOnSpill

options.removeOnSpill

options.direction

options.invalid

options.mirrorContainer

options.ignoreInputTextSelection

API

drake.containers

drake.dragging

drake.start(item)

drake.end()

drake.cancel(revert)

drake.remove()

drake.on (Events)

drake.canMove(item)

drake.destroy()

CSS

Contributing

Support

License

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days

`dragula(containers?, options?)`

`options.containers`

`options.isContainer`

`options.moves`

`options.accepts`

`options.copy`

`options.copySortSource`

`options.revertOnSpill`

`options.removeOnSpill`

`options.direction`

`options.invalid`

`options.mirrorContainer`

`options.ignoreInputTextSelection`

`drake.containers`

`drake.dragging`

`drake.start(item)`

`drake.end()`

`drake.cancel(revert)`

`drake.remove()`

`drake.on` (Events)

`drake.canMove(item)`

`drake.destroy()`