@formkit/drag-and-drop

DragAndDrop for Vue

💻 Install (hypothetically)

via npm

npm install @formkit/dragAndDrop

or via yarn

yarn add @formkit/dragAndDrop

or via pnpm

pnpm install @formkit/dragAndDrop

Intro

This package uses HTML's native drag and drop API .

🕹 Usage

Sortability

The two required arguments for dragAndDrop are parent and values. Parent represents the parent element for the items that are intended to be made draggable. The parent can be passed either as a template ref or as an HTML element. Values is the array of values that will be iterated over in the template script. The values must be type of Ref<Array<any>>.

Important notes:

• Only the immediate children of myList will become draggable.
• The values you are iterating over, in myListValues, must be keyed with unique values in order for Vue to properly rerender when sorting occurs.
• You do not necessarily need to pass a ref to the parent key of dragAndDrop. You can call dragAndDrop by instead passing an HTML element.

<script setup>
import { dragAndDrop } from '@formkit/dragAndDrop';

const myList = ref(null)
const myListValues = ref(['Apple', 'Banana', 'Orange'])

dragAndDrop({
  parent: myList,
  values: myListValues
})
</script>

<template>
  <div ref="myList">
    <div v-for="item in myListValues" :key="item">
      <div>{{ item }}</div>
    </div>
  </div>
</template>

By default, all immediate children of a parent will become draggable. To filter which children become draggable, assign the draggable property of settings.

<script setup>
import { dragAndDrop } from '@formkit/dragAndDrop';

const myList = ref(null)
const myListValues = ref(['Apple', 'Banana', 'Orange'])

dragAndDrop({
  parent: myList,
  values: myListValues,
  settings: {
    draggable: (node: HTMLElement) => {
      return child.classList.contains('item')
    }
  }
})
</script>

<template>
  <div ref="myList">
    <h2>My List</h2>
    <div v-for="item in myListValues" :key="item" class="item">
      <div>{{ item }}</div>
    </div>
  </div>
</template>

Transferability

Additionally, if we specify two separate lists, they will allow both sortability (within the list itself) as well as transferability between each other. Notice that instead of passing a single object to dragAndDrop, we are instead passing an array of objects.

Important notes:

• The items that are transferred from their respective parent lists will be hidden when dragging the element over a new list. The dragged element's value will not be removed from the original list until a drop occurs. Why? In the case that a user "drops" their dragged item off the browser, the dragend event will not fire if the dragged element is removed from its parent. Setting these transferred nodes to display: none circuments that issue.

<script setup>
import { dragAndDrop } from '@formkit/dragAndDrop';

const list1 = ref(null)
const list2 = ref(null)
const list1Values = ref(['Apple', 'Banana', 'Orange'])
const list2Values = ref(['Strawberry', 'Pear'])

dragAndDrop([
  {
    parent: list1,
    values: list1Values
  },
  {
    parent: list2,
    values: list2Values
  }
])
</script>

<template>
  <div>
    <div ref="list1">
      <div v-for="item in list1Values" :key="item">
        <div>{{ item }}</div>
      </div>
    </div>
    <div ref="list2">
      <div v-for="item in list2Values" :key="item">{{ item }}</div>
    </div>
  </div>
</template>

In this example, let's say we had three lists. The first two we wanted to be able to transfer between each other, but the third we wanted to only be sortable. We can scope transferability between lists by specifying a group name in settings like so:

<script setup>
import { dragAndDrop } from '@formkit/dragAndDrop';

const list1 = ref(null)
const list2 = ref(null)
const list3 = ref(null)
const list1Values = ref(['Apple', 'Banana', 'Orange'])
const list2Values = ref(['Strawberry', 'Pear'])
const list3Values = ref(['Grapefruit', 'Watermelon'])

dragAndDrop([
  {
    parent: list1,
    values: list1Values,
    settings: {
      group: 'A'
    }
  },
  {
    parent: list2,
    values: list2Values,
    settings: {
      group: 'A'
    }
  },
  {
    parent: list3,
    values: list3Values,
    settings: {
      group: 'B'
    }
  }
])
</script>

<template>
  <div>
    <div ref="list1">
      <div v-for="item in list1Values" :key="item">
        <div>{{ item }}</div>
      </div>
    </div>
    <div ref="list2">
      <div v-for="item in list2Values" :key="item">{{ item }}</div>
    </div>
    <div ref="list3">
      <div v-for="item in list3Values" :key="item">{{ item }}</div>
    </div>
  </div>
</template>

🎯 DropZones

<script setup>
import { dragAndDrop } from '@formkit/dragAndDrop';

const list1 = ref(null)
const list2 = ref(null)
const list1Values = ref(['Apple', 'Banana', 'Orange'])
const list2Values = ref(['Strawberry', 'Pear'])

let firstListDropZone = ref(null)

dragAndDrop([
  {
    parent: list1,
    values: list1Values,
    settings: {
      dropZones: [firstListDropZone]
    }
  },
  {
    parent: list2,
    values: list2Values
  }
])
</script>

<template>
  <div>
    <div ref="list1">
      <div v-for="item in list1Values" :key="item">
        <div>{{ item }}</div>
      </div>
    </div>
    <div ref="list2">
      <div v-for="item in list2Values" :key="item">{{ item }}</div>
    </div>
    <div ref="firstListDropZone">
      <img
        ref="firstListDropZone"
        src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/WA_80_cm_archery_target.svg/220px-WA_80_cm_archery_target.svg.png"
      />
    </div>
  </div>
</template>

🎚️ Settings

type DragAndDropCollection = Array<DragAndDrop>;

interface DragAndDrop {
  parent: HTMLElement | Ref<HTMLElement | null>;
  values: Ref<Array<any>>;
  settings?: Settings;
}

interface Settings {
  disabled?: boolean; // Disables drag and drop functionality
  draggable?: (child: HTMLElement) => boolean; // Determines which elements should be draggable
  dropZones?: Array<HTMLElement | Ref<HTMLElement | null>>; // Defines arbitrary elements for allow drops.
  group?: string; // Scopes which parent's should be able to transfer items between each other.
  hideNodes?: boolean; // Mode for preventing values from ever being removed from a given list, only hidden.
  isDropZone?: boolean; // Determines whether the parent container should act as a dropZone.
  multiDragConfig?: MultiDragConfig;
  root?: Document | ShadowRoot;
  singleDragConfig?: SingleDragConfig;
  sortable?: boolean; // Determines whether the parent should be sortable.
}

function dragAndDrop(data: DragAndDropCollection | DragAndDrop) {}

export interface MultiDragConfig {
  selector?: string;
  setDragImage?: (
    clonedDraggedEls: HTMLElement[],
    draggedEls: HTMLElement[],
    x: number,
    y: number
  ) => [HTMLElement, number, number];
  transitClass?: string;
  originalClass?: string;
}

export interface SingleDragConfig {
  setDragImage?: (
    clonedEl: HTMLElement,
    draggedEl: HTMLElement,
    x: number,
    y: number
  ) => [HTMLElement, number, number];
  transitClass?: string;
  originalClass?: string;
}

Multi-Drag