README.md

vue3-dragula

👌 Drag and drop so simple it hurts

Vue3 wrapper library for dragula.
^{Written in typescript.}

Based on vue-dragula from @Astray-git.

---

Install

The library is available on npm as vue3-dragula.

npm install --save vue3-dragula

Setup

First import the ‘VueDagula’ plugin from ‘vue3-dragula’ and then add it to your vue3 app.

import { createApp } from 'vue';
import App from './App.vue';

// Import of the VueDragula plugin
import { VueDragula } from 'vue3-dragula';
// Required for dragula's css effects to work
import 'dragula/dist/dragula.min.css'

const vueApp = createApp(App);

// Adding the plugin to the vue app
vueApp.use(VueDragula);

vueApp.mount('#app')

Usage

The functionality of the plugin can be used in your vue components. The template of two lists with items that can be dragged and dropped could look like the following example.

<div class="container-wrapper">
  <div class="container" v-dragula="itemListOne" bag="bag-one">
    <div v-for="item in itemListOne" :key="item.id">{{ item.text }}</div>
  </div>
  <div class="container" v-dragula="itemListTwo" bag="bag-one">
    <div v-for="item in itemListTwo" :key="item.id">{{ item.text }}</div>
  </div>
</div>

Attribute explanation

v-dragula

The v-dragula attribute will make the element it is attached to into a container used by dragula.
The value given to the attribute is an array of all the items in the container.

The array of items needs to be the same as the one that is used to load the item elements with v-for.
The key attribute should be used together with v-for to ensure that vue will render the list correctly.

To learn more on how to use v-for and key, please read the official vue3 documentation about v-for.

bag

The bag attribute takes a string as its value, that represents the name of the bag.
A bag is a collection of multiple containers allocated to the same dragula instance.
All containers that should be dragged and dropped in between, need to be in the same bag.
(As seen in the usage sample. )

APIs

The APIs can be accessed through the VueDragulaGlobal object, which can be important from vue3-dragula.

import { VueDragulaGlobal } from 'vue3-dragula';

options(name, options)

The options function provides the functionality of configuring a dragula instance.
The name parameter should be a string containing the name of the bag, and the options parameter should be a dragula options object.

More infos about dragula options can be found in the dragula documentation.

VueDragulaGlobal.options('bag-one', {
  moves: function (el, source, handle, sibling) {
    return checkElementMove(el, source, handle);
  },
  direction: 'vertical',
  copy: false
});

injectOptions(name, options)

The inject options function provides the functionality of injecting new dragula options into an existing bag instance.
This will override the existing configuration.
Only the existing containers will be keeped.
The name parameter should be a string containing the name of the bag, and the options parameter should be a dragula options object.

More infos about dragula options can be found in the dragula documentation.

VueDragulaGlobal.injectOptions('bag-one', {
  moves: function (el, source, handle, sibling) {
    return checkElementMove(el, source, handle);
  },
  direction: 'horizontal',
  copy: true
});

find(name)

The find function returns a Bag object, depending on the provided bag name.
If the bag with the provided name does not exist, the method will return null.

The returned Bag object contains the name of the bag and the drake of the dragula instance.

More infos about the drake object can be found in the dragula documentation.

const bagOne = VueDragulaGlobal.find('bag-one');

Events

The events can be accessed through the VueDragulaGlobal objects event bus, which can be important from vue3-dragula.

import { VueDragulaGlobal } from 'vue3-dragula';

The dragula instance events can be accessed from the event bus.

More infos about the dragula events can be found in the dragula documentation.

VueDragulaGlobal.eventBus.on('drop', (args) => {
  console.log(args);
});

vue3-dragula Events

Event Name	Listener Arguments	Event Description
dropModel	bagName, el, elModel, target, source, dropIndex	Model was synced, dropIndex exposed
removeModel	bagName, el, container, removeIndex	Model was synced, removeIndex exposed
cancelModel	bagName, el, elModel, source	Model drag action was canceld