Vue Draggable Plus

Common errors

• Property 'Options' does not exist on type 'typeof import("vue-draggable-plus")'.

  cause Attempting to import or use TypeScript types (like `Options` or `SortableEvent`) directly from `vue-draggable-plus` in versions prior to 0.4.1, where they were not correctly exported or defined.
  fix Upgrade `vue-draggable-plus` to version `0.4.1` or newer. For `SortableEvent` and other core Sortablejs types, import them directly from `sortablejs` (e.g., `import type { SortableEvent } from 'sortablejs';`).

• Data does not update when adding or removing items from a `v-model` bound list after a drag operation.

  cause A bug in `vue-draggable-plus` versions prior to 0.5.0 prevented the `update:model-value` event from firing correctly when items were added or removed, only handling reordering.
  fix Update `vue-draggable-plus` to version `0.5.0` or newer. If stuck on an older version, manually update your data array based on the `onAdd` or `onRemove` events.

• The `onMove` callback function is not preventing items from being dragged, even when it returns `false`.

  cause A defect in `vue-draggable-plus` versions prior to 0.5.3 caused the return value of the `onMove` callback to be ignored, failing to prevent the element from being dragged.
  fix Upgrade `vue-draggable-plus` to version `0.5.3` or newer.

Warnings

• gotcha Prior to version 0.5.0, the `v-model` (which uses `update:model-value`) might not have correctly triggered updates when items were added or removed from the draggable list, potentially leading to out-of-sync data in your application state.
  Fix: Upgrade `vue-draggable-plus` to version `0.5.0` or newer to ensure `v-model` reactivity for add/remove operations.
• gotcha In TypeScript projects, obtaining correct types for `Sortablejs` options (e.g., `Options`) and events (e.g., `SortableEvent`) directly from `vue-draggable-plus` was problematic in older versions, leading to type errors or needing workarounds.
  Fix: Update `vue-draggable-plus` to version `0.4.1` or later. For `SortableEvent` specifically, consider importing `SortableEvent` directly from `sortablejs` for robustness if issues persist.
• gotcha The `onMove` callback, which allows you to prevent dragging of specific items by returning `false`, did not function correctly in versions prior to 0.5.3, meaning it was impossible to programmatically stop a drag action.
  Fix: Upgrade `vue-draggable-plus` to version `0.5.3` or newer to restore the intended functionality of the `onMove` callback for preventing drag actions.

Install

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

Imports

• VueDraggable
  wrong:

  const VueDraggable = require('vue-draggable-plus').VueDraggable

  correct:

  import { VueDraggable } from 'vue-draggable-plus'

  Primary component for declarative drag-and-drop usage. This package is ESM-first, CJS `require` is generally discouraged.
• useDraggable
  wrong:

  import VueDraggable from 'vue-draggable-plus'

  correct:

  import { useDraggable } from 'vue-draggable-plus'

  Composition API composable for programmatic drag-and-drop control. Commonly misused as a default import.
• vDraggable
  wrong:

  import { Draggable } from 'vue-draggable-plus'

  correct:

  import { vDraggable } from 'vue-draggable-plus'

  Directive for concise drag-and-drop functionality directly on an element. The directive name starts with 'v' and uses named export.
• SortableEvent
  wrong:

  import type { SortableEvent } from 'vue-draggable-plus'

  correct:

  import type { SortableEvent } from 'sortablejs'

  While `vue-draggable-plus` exposes some types, for core Sortablejs event types, directly importing from `sortablejs` is the standard and often more reliable approach.

Quickstart

This quickstart demonstrates how to set up a basic draggable list using the `useDraggable` Composition API composable, binding it to a `ref` element and a reactive array. It includes basic styling and logs drag events.

```typescript
<template>
  <div ref="el" class="drag-container">
    <div v-for="item in list" :key="item.id" class="drag-item">
      {{ item.name }}
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useDraggable } from 'vue-draggable-plus'

interface ListItem {
  name: string;
  id: number;
}

const el = ref<HTMLElement | null>(null)
const list = ref<ListItem[]>([
  { name: 'Item A', id: 1 },
  { name: 'Item B', id: 2 },
  { name: 'Item C', id: 3 },
  { name: 'Item D', id: 4 }
])

const draggable = useDraggable(el, list, {
  animation: 150,
  onStart() {
    console.log('Drag started')
  },
  onEnd(event) {
    console.log('Drag ended:', event.oldIndex, '->', event.newIndex)
    // The list.value is automatically updated by useDraggable
  }
})

onMounted(() => {
  // For demonstration, you could programmatically start/destroy draggable if needed
  // console.log('Draggable instance:', draggable)
})
</script>

<style>
.drag-container {
  border: 1px solid #eee;
  padding: 10px;
  min-height: 100px;
}
.drag-item {
  padding: 8px 12px;
  margin-bottom: 5px;
  background-color: #f9f9f9;
  border: 1px solid #ddd;
  cursor: grab;
}
.drag-item:hover {
  background-color: #f0f0f0;
}
</style>
```