Guide · Open source
How to use Vue.Draggable: install and build a sortable list
Updated · written with AI from the project's own documentation and checked against our catalogue data
Vue.Draggable (published on npm as vuedraggable) is a Vue component that lets users reorder items in a list by dragging them, and move items between lists. It wraps Sortable.js and keeps your app's array in sync with what the user dragged. This guide shows you how to install it, wire it to an array with v-model, and use the main props, so you can add drag-to-reorder to a Vue 2 app.
Vue.DraggableSortableJS/Vue.Draggable · ★ 20.5k · MIT Install options & downloads Quick start
- 1Confirm Vue 2. Check that your project uses Vue.js 2.0. For Vue 3, the README points to vue.draggable.next instead.
- 2Install vuedraggable. Run yarn add vuedraggable or npm i -S vuedraggable in your project.
- 3Import and register. Import draggable from 'vuedraggable' in your component and add it to the components option.
- 4Wrap your list. Wrap the v-for elements in the draggable component and bind your array with v-model.
- 5Add unique keys. Give each item in the v-for a unique :key, such as element.id.
- 6Tune behaviour. Set Sortable.js options such as handle, group, ghost-class or sort as props when you need them.
- 7Handle events or cancel moves. Use the @change and other events for changes, or the move prop to return false and cancel a drag.
Check that Vue.Draggable fits your project
Vue.Draggable is built for Vue.js 2. The README says a separate project, vue.draggable.next, handles Vue 3, so check your Vue version before you install.
You need Vue.js 2.0, Node.js and npm or yarn, as listed in the project's prerequisites. It is MIT licensed and written in JavaScript.
- Use vuedraggable for Vue 2.0. The README warns not to confuse it with vue-draggable, which is for Vue 1.0.
- Vue.Draggable is a Vue-specific wrapper, so it is not useful outside Vue.
Install vuedraggable with npm or yarn
Install the package with your package manager of choice. The README gives both commands below.
If you do not use a build tool, the README also shows a direct script-tag setup that loads Vue, Sortable.js and the Vue.Draggable UMD build from CDNs.
yarn add vuedraggable
npm i -S vuedraggableBuild a basic drag-to-reorder list
Import the component in your .vue file and register it under components. Then wrap the elements you want to reorder with the draggable component and bind your array with v-model.
Each item in the v-for needs a unique key, such as element.id, as shown in the README example. Use @start and @end to track when a drag begins and ends.
- Set v-model to the array you want to keep in sync.
- Give each child element a :key so Vue can track it.
- Draggable should directly wrap the draggable elements, or a transition-component containing them.
<draggable v-model="myArray" group="people" @start="drag=true" @end="drag=false">
<div v-for="element in myArray" :key="element.id">{{element.name}}</div>
</draggable>
// .vue file
import draggable from 'vuedraggable'
export default {
components: {
draggable,
},
}Use Vuex or transition-group with your list
If your list lives in Vuex, bind v-model to a computed property with a getter that reads from the store and a setter that commits a mutation. The README notes that v-model is the preferred way to use the component because it is compatible with Vuex.
To animate moves, wrap the v-for elements in a transition-group inside the draggable component. The README says Vue.Draggable is compatible with Vue.js 2.0 transition-group.
computed: {
myList: {
get() {
return this.$store.state.myList
},
set(value) {
this.$store.commit('updateList', value)
}
}
}Set group, handle and other Sortable.js options
Since version 2.19, all Sortable.js options can be set directly as props on the draggable component. Kebab-case names are converted for you, so ghost-class becomes the ghostClass option. The README notes the exception: options whose names start with "on" are not valid props, because the component exposes the same API as events.
Use group to allow dragging between lists. Use handle to restrict dragging to a specific element, and sort to disable reordering within a list.
- handle: a selector for the element users grab to drag.
- group: an object with name, pull and put, for example to allow cloning from one list into another.
- ghost-class: a CSS class applied to the placeholder while dragging.
- sort: set to false to stop reordering inside the list.
- tag: the HTML element or Vue component used as the outer wrapper.
<draggable
v-model="list"
handle=".handle"
:group="{ name: 'people', pull: 'clone', put: false }"
ghost-class="ghost"
:sort="false"
@change="log"
>
</draggable>Cancel a move with the move prop
The move prop takes a function that behaves like the Sortable.js onMove callback. Return false from it to cancel the drag. The event object includes draggedContext and relatedContext, which give you the dragged element, its index, and the target list and index.
The README example refuses to move any element whose name is 'apple'. Use the same pattern to block moves your app should not allow.
<draggable :list="list" :move="checkMove">
checkMove: function(evt){
return (evt.draggedContext.element.name!=='apple');
}What people use it for
- Reordering a priority list or task board column in a Vue 2 app.
- Dragging items between two or more lists, using the group option.
- Keeping a Vuex-stored list in sync with what the user dragged, using a computed v-model.
- Making components from a UI library draggable by passing them through the tag and componentData props.
Frequently asked questions
Is Vue.Draggable free to use?
Yes. The project is licensed under the MIT License, as shown in the README badge and the LICENSE file linked from it. Check the LICENSE file in the repository for the full terms.
Does Vue.Draggable work with Vue 3?
The README says Vue.Draggable is for Vue.js 2.0 and points to a separate project, vue.draggable.next, for Vue 3. Use that project if your app runs Vue 3.
What is the difference between vuedraggable and vue-draggable?
The README warns that vuedraggable is for Vue 2.0 and that vue-draggable is for Vue 1.0. Install the package name that matches your Vue version.
What are the requirements to install Vue.Draggable?
The prerequisites are Vue.js 2.0, Node.js and npm or yarn. Install it with yarn add vuedraggable or npm i -S vuedraggable.
Can I use Vue.Draggable with Vuex?
Yes. The README shows a computed property with a getter that reads from the store and a setter that commits a mutation, bound to v-model on the draggable component.
What are the alternatives to Vue.Draggable?
The README lists Sortable.js, vue-draggable-next and vuedraggable-next as comparable projects. Sortable.js is the library Vue.Draggable wraps, so use it directly if you do not need the Vue binding.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Vue.Draggable is a good choice for Vue 2 developers who want drag-to-reorder lists, drag between lists and Sortable.js features with v-model sync. If your project uses Vue 3, or you do not use Vue at all, pick vue.draggable.next or plain Sortable.js instead.
Install options & downloads