Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VueDraggable
✓ import { VueDraggable } from 'vue-draggable-plus'
✗ const VueDraggable = require('vue-draggable-plus').VueDraggable
Primary component for declarative drag-and-drop usage. This package is ESM-first, CJS `require` is generally discouraged.
useDraggable
✓ import { useDraggable } from 'vue-draggable-plus'
✗ import VueDraggable from 'vue-draggable-plus'
Composition API composable for programmatic drag-and-drop control. Commonly misused as a default import.
vDraggable
✓ import { vDraggable } from 'vue-draggable-plus'
✗ import { Draggable } 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
✓ import type { SortableEvent } from 'sortablejs'
✗ import type { SortableEvent } from 'vue-draggable-plus'
While `vue-draggable-plus` exposes some types, for core Sortablejs event types, directly importing from `sortablejs` is the standard and often more reliable approach.
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>
```
Errors
Common errors & fixes
Property 'Options' does not exist on type 'typeof import("vue-draggable-plus")'.
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.
fixUpgrade `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.
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.
fixUpdate `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`.
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.
fixUpgrade `vue-draggable-plus` to version `0.5.3` or newer.
Audit
Dependencies
@types/sortablejsoptionalPeer dependency for TypeScript definitions when working with Sortablejs options.
sortablejsrequiredUnderlying drag-and-drop library. While not a direct peer dependency in package.json, it's the core engine this library wraps.