vue-draggable-next

You can customize the visual appearance of elements during the drag process by using the ghost-class, chosen-class, and drag-class props. These props allow you to apply specific CSS classes to the placeholder (ghost), the element currently selected (chosen), and the element being actively dragged (drag).

<!-- Component configuration -->
<draggable 
  v-model="list"
  :animation="300"
  easing="cubic-bezier(0.4, 0, 0.2, 1)"
  ghost-class="ghost"
  chosen-class="chosen"
  drag-class="drag"
>
  <!-- items -->
</draggable>

/* Corresponding CSS */
.ghost {
  opacity: 0.5;
  background: #c8ebfb;
  border: 2px dashed #2196f3;
}

.chosen {
  transform: rotate(5deg);
}

.drag {
  transform: rotate(0deg;
}

You can execute the test suite using the following commands via npm or npx:

• Run all tests: npm run test
• Run with coverage: npm run test:unit
• Run a specific test file: npx jest <path_to_file>
• Run in watch mode: npx jest --watch
• Full CI/CD suite (types, unit, and build): npm test

# Run all tests
npm run test

# Run with coverage
npm run test:unit

# Run specific test file
npx jest __tests__/basic-examples.test.ts

# Run in watch mode
npx jest --watch

When migrating from the Vue 2 version of vue-draggable-next to the Vue 3 version, note that this package is strictly for Vue 3.

The recommended way to implement the component in Vue 3 is using the item-key prop combined with the #item slot. This provides better performance and follows the Vue 3 pattern for list rendering. While the traditional v-for approach still works, using the slot pattern is preferred.

<!-- Recommended Vue 3 approach using item-key and #item slot -->
<draggable v-model="list" item-key="id" @end="onEnd">
  <template #item="{ element }">
    <div>{{ element.name }}</div>
  </template>
</draggable>

You can install vue-draggable-next using npm, yarn, or pnpm.

# npm
npm install vue-draggable-next

# yarn  
yarn add vue-draggable-next

# pnpm
pnpm add vue-draggable-next

While vue-draggable-next works out of the box on mobile, you can improve the user experience by applying specific CSS to your draggable items. Recommended practices include preventing text selection during drags and ensuring touch targets are large enough.

.drag-item {
  /* Prevent text selection during drag */
  user-select: none;
  -webkit-user-select: none;
  
  /* Better touch targets */
  min-height: 44px;
  
  /* Smooth feedback */
  transition: transform 0.2s ease;
}

.drag-item:active {
  transform: scale(1.02);
}

Global Registration (Vue 3)

Use app.component on your Vue application instance.

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

const app = createApp({})
app.component('draggable', VueDraggableNext)

Local Registration

Register the component within your component's components option.

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

export default {
  components: {
    draggable: VueDraggableNext
  }
}

The move prop allows you to intercept and potentially cancel a drag operation before it happens. It is a function that receives an event object and the original Sortable event.

When move is called, the event object is augmented with:

• relatedContext: Information about the target list/component being hovered over.
• draggedContext: Information about the item currently being dragged.

Return true to allow the move, or false to cancel it.

If you encounter issues with vue-draggable-next, check the following:

1. Items not dragging: Verify that the disabled prop is set to false and that every item in your list has a unique key.
2. Performance issues: Ensure you are using the item-key prop to allow the library to track items efficiently.
3. Touch not working: Check your CSS for touch-action properties that might be preventing touch events from reaching the component.
4. Transitions glitching: If using transitions, try setting tag="transition-group" and ensure you are using the correct transition classes.

While basic usage works, for better performance in Vue 3, you should use the item-key prop and the #item slot pattern. This allows the library to track items more efficiently.

<template>
  <draggable v-model="list" item-key="id" @change="onChange">
    <template #item="{ element }">
      <div>{{ element.name }}</div>
    </template>
  </draggable>
</template>