Vue 3 Draggable Component

Common errors

• Property 'VueDraggableNext' does not exist on type 'typeof import("...")'

  cause Incorrect import statement; attempting a default import when it's a named export.
  fix Change `import VueDraggableNext from 'vue-draggable-next'` to `import { VueDraggableNext } from 'vue-draggable-next'`.

• Argument of type '(...)' is not assignable to parameter of type 'never'.

  cause Often seen when TypeScript cannot infer the type of elements in the `v-model` list or within event handlers, particularly if `item-key` is missing or types are not explicitly defined.
  fix Ensure your list is strongly typed (e.g., `list = ref<Person[]>()`) and that `item-key` is correctly set, allowing TypeScript to better track item types.

• [Vue warn]: Injection "Symbol(component:setup-context)" not found.

  cause This warning can occur when a component expected to be rendered within a Vue context is not, or when there are mismatched Vue versions in your project.
  fix Verify that `vue-draggable-next` is correctly installed and imported, and that your build setup is using a consistent Vue 3 version. Clear node_modules and reinstall dependencies.

Warnings

• breaking When migrating from `vue-draggable` (Vue 2) to `vue-draggable-next` (Vue 3), the Vue 2 lifecycle hooks like `beforeDestroy` have been renamed to `beforeUnmount` in Vue 3. Ensure your custom component logic adapts to these new names.
  Fix: Update all instances of `beforeDestroy` to `beforeUnmount` in your Vue 3 component lifecycle hooks.
• gotcha The `item-key` prop is crucial for Vue's efficient re-rendering and tracking of list items, especially during drag-and-drop operations. Failing to provide a stable, unique `item-key` can lead to unexpected behavior, performance issues, or incorrect list state.
  Fix: Always define a unique `item-key` prop on the `draggable` component, typically corresponding to a unique ID on each item in your `v-model` list (e.g., `:item-key="'id'"`).
• gotcha Versions prior to 2.2.1 had issues with missing TypeScript definition files, leading to type errors or incomplete IntelliSense when used in TypeScript projects.
  Fix: Upgrade to `vue-draggable-next` version 2.2.1 or higher to ensure proper TypeScript definition files are included and recognized.
• gotcha For `v-model` to work correctly with drag-and-drop, Vue requires the underlying data to be reactive. While `vue-draggable-next` handles internal updates, ensure the list passed to `v-model` (or `list`) is a reactive reference.
  Fix: In Composition API, use `ref([])` or `reactive([])` for your list data. In Options API, define your list within the `data` property of your component.

Install

• npm install vue-draggable-next npm
• yarn add vue-draggable-next yarn
• pnpm add vue-draggable-next pnpm

Imports

• VueDraggableNext
  wrong:

  import VueDraggableNext from 'vue-draggable-next'

  correct:

  import { VueDraggableNext } from 'vue-draggable-next'

  VueDraggableNext is a named export. It is often aliased as `draggable` in the component's `components` option for brevity.
• draggable

  import { VueDraggableNext as draggable } from 'vue-draggable-next'

  Common practice to alias VueDraggableNext to 'draggable' for cleaner template usage.

Quickstart

This example demonstrates a basic draggable list using Vue 3's Composition API and TypeScript, allowing users to reorder items.

<template>
  <div class="drag-container">
    <draggable 
      v-model="list" 
      group="people" 
      @change="onListChange"
      item-key="id"
    >
      <template #item="{ element }">
        <div class="drag-item">
          {{ element.name }}
        </div>
      </template>
    </draggable>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { VueDraggableNext } from 'vue-draggable-next'

interface Person {
  id: number
  name: string
}

const list = ref<Person[]>([
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' },
  { id: 3, name: 'Bob' }
])

const onListChange = (event: any) => {
  console.log('List changed:', event)
}
</script>

<style scoped>
.drag-container {
  min-height: 200px;
  padding: 20px;
  border: 1px dashed #ccc;
}

.drag-item {
  padding: 10px;
  margin: 5px 0;
  background: #f0f0f0;
  border-radius: 4px;
  cursor: grab;
  transition: background 0.2s;
}

.drag-item:hover {
  background: #e0e0e0;
}
</style>