Dragula

:ok_hand: Drag and drop so simple it hurts

Generate Convert Improve

Install / Use

/learn @bevacqua/Dragula

About this skill

Quality Score

0/100

README

[![logo.png][3]][2]

Drag and drop so simple it hurts

Browser support includes every sane browser and IE7+. <sub>(Granted you polyfill the functional Array methods in ES5)</sub>

Framework support includes vanilla JavaScript, Angular, and React.

Official [Angular bridge][8] for dragula [(demo)][10]
Official [Angular 2 bridge][22] for dragula [(demo)][23]
Official [React bridge][9] for dragula [(demo)][11]

Demo

[![demo.png][1]][2]

Try out the [demo][2]!

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][15]. 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][16] you need to incorporate in order for dragula to work as expected.

You can add them by including [dist/dragula.css][12] or [dist/dragula.min.css][13] 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 insid

Related Skills

node-connect

340.5k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

84.2k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

340.5k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

commit-push-pr

84.2k

Commit, push, and open a PR