Vue Draggable ES

Common errors

• [Vue warn]: Failed to resolve component: draggable

  cause The `draggable` component was not correctly imported or registered in your Vue application.
  fix Ensure `import draggable from 'vuedraggable-es'` is present in your script and that `draggable` is registered in your component's `components` option or globally if not using `<script setup>`.

• Property 'item-key' is missing in type '{ ... }' but required in type '{ itemKey: any; }'.

  cause This TypeScript error indicates that the mandatory `item-key` prop for `vuedraggable-es` in Vue 3 is missing.
  fix Add the `item-key` prop to the `<draggable>` component, e.g., `:item-key="'id'"`, pointing to a unique identifier property within your list items.

• Uncaught TypeError: vue.defineComponent is not a function

  cause You are attempting to use `vuedraggable-es` (designed for Vue 3) within a Vue 2 project, leading to incompatibility with Vue 3-specific APIs.
  fix If your project is Vue 2, you must uninstall `vuedraggable-es` and install the `vuedraggable` package. If your project is Vue 3, ensure your `vue` package version meets the `vuedraggable-es` peer dependency requirements (e.g., `^3.2.31`).

Warnings

• breaking This package, `vuedraggable-es`, is specifically designed for Vue 3 and is incompatible with Vue 2 or earlier versions. Attempting to use it in a Vue 2 project will result in runtime errors related to Vue's internal APIs.
  Fix: For Vue 2 projects, you must use the `vuedraggable` package (without the `-es` suffix). For Vue 3 projects, ensure your `vue` peer dependency is `^3.2.31` or higher for `vuedraggable-es`.
• gotcha When using `vuedraggable-es` with Vue 3, the `item-key` prop is mandatory. This prop is crucial for Vue's reactivity system to track elements efficiently, especially when reordering or using `transition-group`.
  Fix: Always provide a unique `item-key` prop that points to a stable identifier on your list items, e.g., `:item-key="'id'"` or `:item-key="element => element.uniqueId"`.
• breaking The usage of `transition-group` with `vuedraggable-es` requires a specific structure. The `transition-group` component should be effectively 'aliased' by passing `tag="transition-group"` to the `draggable` component, and then the list items are rendered via the `#item` slot.
  Fix: Ensure your structure follows the pattern: `<draggable v-model="myArray" tag="transition-group" item-key="id"><template #item="{element}"><div>{{element.name}}</div></template></draggable>`.
• gotcha The `vuedraggable-es` package is an ES module (ESM) and is not intended for direct use with CommonJS `require()` statements or in environments that do not support ESM. This is reflected in its package name suffix `-es`.
  Fix: Always use `import draggable from 'vuedraggable-es'` and ensure your build setup (Vite, Webpack, Rollup) is configured to handle ES modules correctly. If you encounter issues, verify your `package.json` `type` field is set to `module` or that your bundler explicitly handles ESM.

Install

• npm install vuedraggable-es npm
• yarn add vuedraggable-es yarn
• pnpm add vuedraggable-es pnpm

Imports

• draggable
  wrong:

  const draggable = require('vuedraggable-es')

  correct:

  import draggable from 'vuedraggable-es'

  This package (`vuedraggable-es`) is an ES module and exports the `draggable` component as its default export. While some documentation or older examples might show `import draggable from 'vuedraggable'`, the correct import path for the `vuedraggable-es` package is `vuedraggable-es`.
• DraggableComponent

  import type { DraggableComponent, DraggableEvents } from 'vuedraggable-es'

  TypeScript type definitions are available for the component's props, events, and other related types, enhancing developer experience in TypeScript projects.
• VueDraggable (UMD)

  <script src="//cdnjs.cloudflare.com/ajax/libs/Vue.Draggable/4.0.0/vuedraggable.umd.min.js"></script>

  For direct browser usage via CDN, the `VueDraggable` global is exposed. Note that the CDN example often references an older `vuedraggable` package version (e.g., 4.0.0), which may differ from the latest `vuedraggable-es` npm package behavior. Verify compatibility for your specific use case.

Quickstart

Demonstrates a basic draggable list using `vuedraggable-es` with Vue 3's Composition API, `v-model` for synchronization, and event handling for drag start/end states in a single file component.

<script setup>
import draggable from 'vuedraggable-es'
import { ref } from 'vue'

const myArray = ref([
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' },
  { id: 3, name: 'Item 3' },
]);
const drag = ref(false);

function handleStart() {
  drag.value = true;
  console.log('Drag started');
}

function handleEnd() {
  drag.value = false;
  console.log('Drag ended', myArray.value);
}
</script>

<template>
  <div style="font-family: sans-serif; padding: 20px;">
    <h2>Draggable List</h2>
    <p>Drag status: {{ drag ? 'Dragging' : 'Not dragging' }}</p>
    <draggable
      v-model="myArray"
      group="people"
      @start="handleStart"
      @end="handleEnd"
      item-key="id"
      style="border: 1px solid #ccc; padding: 10px; min-height: 50px;"
    >
      <template #item="{ element }">
        <div style="background: #f9f9f9; border: 1px solid #eee; margin-bottom: 5px; padding: 8px; cursor: grab;">
          {{ element.name }}
        </div>
      </template>
    </draggable>
    <pre style="background: #eee; padding: 10px; margin-top: 20px;">{{ JSON.stringify(myArray, null, 2) }}</pre>
  </div>
</template>