Migrar desde la v2

La v3 es una reescritura de la v2. El modelo se mantiene: un provider, y composables que llamas sobre tus propios elementos. Pero la mayoría de los nombres y de las opciones cambiaron, la ordenación pasó a la biblioteca, y el handler de drop que escribías para cada lista desaparece. Esta página relaciona cada parte de la v2 con la v3 y luego muestra los casos habituales antes y después.

Qué cambió

• La ordenación viene incluida. En la v2, una lista era una zona de drop, sus filas eran elementos arrastrables con un payload [index, items], y ordenabas en onDrop con e.helpers.suggestSort(). En la v3 lo hacen makeSortableList y makeSortableItem: la lista renderiza un borrador de tu array que se reordena mientras arrastras, y el drop escribe el nuevo array en tu ref. La mayoría de los handlers de drop de la v2 se borran, no se portan.
• Las cosas se mueven solas. Las filas se deslizan a sus nuevos sitios (FLIP), el overlay aterriza en su hueco al soltar y vuelve a su sitio al cancelar. <TransitionGroup> desaparece.
• Sigue siendo un solo paquete. @vue-dnd-kit/core contiene las listas, los árboles, el multi-drag, los modificadores, los sensores y las funciones de colisión. El módulo de Nuxt se mantiene; @vue-dnd-kit/actions (arrastres programáticos) y @vue-dnd-kit/devtools son nuevos y opcionales.
• Un overlay de verdad. Se teletransporta a body y muestra un clon profundo, con el tamaño del hueco en el que aterrizará. Los componentes de overlay reciben el arrastre como props en lugar de leer las interioridades del provider.
• Ids, no elementos. La selección, los eventos y el estado del arrastre usan como clave ids de tus datos. No hay mapas de elementos del DOM que leer.
• Los tipos y las reglas de aceptación sustituyen a groups para los elementos arrastrables simples y los destinos. Las listas intercambian ítems por el nombre de su group.
• Decisiones antes del drop. onBeforeDrop acepta, rechaza, mantiene el arrastre en curso o se queda con parte de los ítems. onDrop solo aplica.
• Sensores. La entrada de puntero y la de teclado son sensores. La activación se configura por tipo de puntero, y los arrastres táctiles empiezan con una pulsación larga, así que las listas se siguen desplazando bajo el dedo.
• Áreas. makeDragArea sustituye a makeConstraintArea y makeAutoScroll, y el desplazamiento automático funciona en todo contenedor desplazable sin código.
• La accesibilidad viene activada por defecto: atributos ARIA, un foco que vuelve tras el drop y anuncios para lectores de pantalla.

Actualizar

npm i @vue-dnd-kit/core@^3

yarn add @vue-dnd-kit/core@^3

pnpm add @vue-dnd-kit/core@^3

bun add @vue-dnd-kit/core@^3

• Una app que tiene "@vue-dnd-kit/core": "^2…" en su package.json se queda en la v2 hasta que el rango diga ^3.
• Vue 3.5 o posterior. La v2 no tenía dependencias; la v3 tiene una, @vueuse/core (14 o 15).
• Navegadores: Chrome y Edge 104+, Safari 15.4+, Firefox 104+.
• La v2 y la v3 comparten nombre de paquete, así que una app pasa a la v3 de una vez. No hay capa de compatibilidad. La documentación de la v2 sigue disponible desde el menú de versiones de la parte superior de la página.

Un buen orden de trabajo:

1. Actualiza los paquetes y renombra las props del provider (más abajo).
2. Convierte cada lista ordenable en makeSortableList y makeSortableItem, y borra su handler de drop.
3. Porta los elementos arrastrables simples y las zonas de drop.
4. Porta las vistas previas personalizadas a componentes de overlay o al slot #overlay del provider.
5. Sustituye makeConstraintArea y makeAutoScroll por makeDragArea, o por nada.
6. Borra los apaños de la v2: tabindex y aria-grabbed en los elementos arrastrables, touch-action: none en ítems enteros, <TransitionGroup> alrededor de las filas, markRaw alrededor de los componentes de vista previa.

De lo antiguo a lo nuevo

Sin equivalente en una tabla significa que la v3 no tiene nada con ese nombre; la celda dice qué usar en su lugar.

De un vistazo

El provider

Props nuevas sin equivalente en la v2: activation, modifiers, sensors, animation, dropAnimation, animateChanges, haptics, copyModifier, overlayFit, overlayClass, overlayTransition, overlayPreviews, announcements, screenReaderInstructions y defaultStyles. El provider también emite drag-start, drag-move, drag-over, drag-end, drag-cancel, drag-resume y drag-settle. Todo está en la guía del provider.

Leer el estado: useDnD

Los eventos pasaron a useDnDMonitor: consulta eventos y decisiones de drop. Las formas completas están en la API de useDnD.

makeDraggable

makeDroppable

El evento de drop

Ordenación

El código de antes y después está más abajo. Todo sobre las listas está en listas ordenables y listas que comparten ítems.

Grupos

La v2 tenía una sola opción groups para todo. La v3 la divide en dos:

Una lista sin group es un grupo propio y no intercambia con ninguna otra lista. En la v2, una zona sin grupos lo aceptaba todo. Consulta qué arrastres acepta un destino.

El overlay

Más en la guía del overlay.

Selección y multi-drag

Más en multi-drag y selección.

Ejes, límites y ajuste

Más en ejes, límites y cuadrículas.

Desplazamiento automático

Teclado y accesibilidad

Más en accesibilidad.

Eventos y decisiones de drop

Un onDrop de la v2 podía devolver un valor, o una promesa de uno, para decidir el drop. En la v3 esa es la tarea de onBeforeDrop, en listas, árboles, destinos de drop y monitores:

Los monitores responden primero, luego el destino. Después se ejecuta el onDrop del destino, una lista escribe sus nuevos arrays y le sigue onDragEnd. Más en decidir un drop y en la API de eventos.

Tipos

Nuxt

npm i @vue-dnd-kit/nuxt@^3 @vue-dnd-kit/core@^3

modules: ['@vue-dnd-kit/nuxt'] en nuxt.config.ts se queda como estaba. Consulta instalación.

Antes y después

Un elemento arrastrable y una zona de drop

v2

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';

const props = defineProps<{ card: Card }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragging } = makeDraggable(el, {
  groups: ['task'],
  dragHandle: '.handle',
  data: () => props.card,
});
</script>

<template>
  <div ref="el" tabindex="0" :class="{ dragging: isDragging }">
    <span class="handle">⋮⋮</span>
    {{ card.title }}
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDroppable } from '@vue-dnd-kit/core';

const emit = defineEmits<{ drop: [cards: Card[]] }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragOver, isAllowed } = makeDroppable(el, {
  groups: ['task'],
  events: {
    onDrop: (e) => emit('drop', e.draggedItems.map((item) => item.data as Card)),
  },
});
</script>

<template>
  <div ref="el" :class="{ over: isDragOver && isAllowed }"><slot /></div>
</template>

v3

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';

const props = defineProps<{ card: Card }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragging } = makeDraggable(el, {
  id: () => props.card.id,   // read back as `active.id`
  type: 'task',              // matched by the targets' `accept`
  handle: '.handle',
  data: () => props.card,
});
</script>

<template>
  <div ref="el" :class="{ dragging: isDragging }">
    <button type="button" class="handle" :aria-label="`Move ${card.title}`">⋮⋮</button>
    {{ card.title }}
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDroppable } from '@vue-dnd-kit/core';

const emit = defineEmits<{ drop: [cards: Card[]] }>();
const el = useTemplateRef<HTMLElement>('el');

const { isOver, isAccepting } = makeDroppable(el, {
  accept: 'task',
  onDrop: (e) => emit('drop', e.active.items.map((item) => item.data as Card)),
});
</script>

<template>
  <div ref="el" :class="{ over: isOver && isAccepting }"><slot /></div>
</template>

• La tarjeta recibe tabindex, role y los atributos aria-* por sí sola. Un asa <button> puede recibir el foco, y los arrastres con teclado empiezan desde ella.
• groups pasó a ser type en el elemento arrastrable y accept en el destino. Los callbacks salieron del objeto events.
• isOver sin isAccepting es un destino que rechaza el arrastre: un drop ahí vuelve a su sitio.

Una lista ordenable

v2

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDroppable, type IDragEvent } from '@vue-dnd-kit/core';
import TaskItem from './TaskItem.vue';

const tasks = defineModel<Task[]>({ required: true });
const el = useTemplateRef<HTMLElement>('el');

makeDroppable(
  el,
  {
    events: {
      onDrop(e: IDragEvent) {
        const r = e.helpers.suggestSort('vertical');
        if (r) tasks.value = r.targetItems as Task[];
      },
    },
  },
  () => tasks.value,
);
</script>

<template>
  <div ref="el">
    <TransitionGroup name="list">
      <TaskItem v-for="(task, index) in tasks" :key="task.id" :task="task" :index="index" :tasks="tasks" />
    </TransitionGroup>
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeDraggable } from '@vue-dnd-kit/core';

const props = defineProps<{ task: Task; index: number; tasks: Task[] }>();
const el = useTemplateRef<HTMLElement>('el');

const { isDragging } = makeDraggable(el, { id: props.task.id }, () => [props.index, props.tasks]);
</script>

<template>
  <div ref="el" :class="{ 'is-dragging': isDragging }">{{ task.title }}</div>
</template>

v3

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeSortableList } from '@vue-dnd-kit/core';
import TaskItem from './TaskItem.vue';

const tasks = defineModel<Task[]>({ required: true });
const el = useTemplateRef<HTMLElement>('el');

const { items } = makeSortableList(el, { items: tasks });
</script>

<template>
  <ul ref="el">
    <TaskItem v-for="task in items" :key="task.id" :task="task" />
  </ul>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { makeSortableItem } from '@vue-dnd-kit/core';

const props = defineProps<{ task: Task }>();
const el = useTemplateRef<HTMLElement>('el');

const { isPlaceholder } = makeSortableItem(el, { item: () => props.task });
</script>

<template>
  <li ref="el" :class="{ slot: isPlaceholder }">{{ task.title }}</li>
</template>

• Renderiza items, el borrador: se reordena mientras arrastras. tasks recibe el nuevo orden al soltar, y defineModel emite update:modelValue.
• Sin índice, sin payload, sin onDrop, sin <TransitionGroup>: las filas se deslizan solas.
• La fila arrastrada se queda en la lista como el hueco en el que aterrizará. Dale estilo con isPlaceholder o [data-dnd-placeholder] en lugar de ocultarla.

Listas que comparten ítems

v2

// Each column's makeDroppable calls this from its onDrop, with its array as the payload.
function applySort(e: IDragEvent) {
  const r = e.helpers.suggestSort('vertical');
  if (!r) return;

  const src = e.draggedItems[0]?.items;
  const tgt = e.hoveredDraggable?.items ?? e.dropZone?.items;

  if (src === todo.value) todo.value = r.sourceItems as Task[];
  else if (src === done.value) done.value = r.sourceItems as Task[];

  if (!r.sameList) {
    if (tgt === todo.value) todo.value = r.targetItems as Task[];
    else if (tgt === done.value) done.value = r.targetItems as Task[];
  }
}

v3

<script setup lang="ts">
import { toRef, useTemplateRef } from 'vue';
import { makeSortableList } from '@vue-dnd-kit/core';
import TaskItem from './TaskItem.vue';

const props = defineProps<{ column: { id: string; tasks: Task[] } }>();
const el = useTemplateRef<HTMLElement>('el');

const { items } = makeSortableList(el, {
  id: props.column.id,                   // `from.list` and `to.list` in drop events
  items: toRef(props.column, 'tasks'),   // writable: the parent passes a reactive column
  group: 'board',                        // same name: tasks move between these lists
});
</script>

<template>
  <ul ref="el">
    <TaskItem v-for="task in items" :key="task.id" :task="task" />
  </ul>
</template>

<script setup lang="ts">
import { reactive } from 'vue';
import Column from './Column.vue';

const columns = reactive([
  { id: 'todo', tasks: [{ id: 't1', title: 'Write the docs' }] },
  { id: 'done', tasks: [] },
]);
</script>

<template>
  <Column v-for="column in columns" :key="column.id" :column="column" />
</template>

El drop escribe los dos arrays, el que la tarea dejó y aquel en el que entró. TaskItem.vue es el de la lista ordenable de arriba. Una paleta que reparte copias era suggestCopy() y un flag copyOnly; ahora es una lista:

makeSortableList(el, {
  items: blocks,
  group: { name: 'board', pull: 'clone', put: false },  // copies go out, nothing comes in
  sort: false,                                          // its own order stays
  clone: (block) => ({ ...block, id: crypto.randomUUID() }),
});

Para un store de Pinia u otro estado que no escribes directamente, pasa items como getter, llama a e.preventDefault() en onDrop y aplica e.result: consulta listas controladas.

Un overlay personalizado

v2

makeDraggable(el, {
  render: markRaw(TaskOverlay),
  data: () => props.task,
});

<script setup lang="ts">
import { computed } from 'vue';
import { useDnDProvider } from '@vue-dnd-kit/core';

const { entities } = useDnDProvider();
const task = computed(() => {
  const [node] = entities.draggingMap.keys();
  return node ? (entities.draggableMap.get(node)?.data?.() as Task) : null;
});
</script>

<template>
  <div class="task-preview">{{ task?.title }}</div>
</template>

v3

makeDraggable(el, {
  id: () => props.task.id,
  overlay: TaskOverlay,
  data: () => props.task,
});

<script setup lang="ts">
import { computed } from 'vue';
import type { DragItem, Over } from '@vue-dnd-kit/core';

const props = defineProps<{ items: DragItem[]; over: Over | null; accepted: boolean }>();
const task = computed(() => props.items[0]!.data as Task);
</script>

<template>
  <!-- Fills the overlay box, which takes the size of the slot. -->
  <div class="task-preview" :class="{ refused: over && !accepted }">
    {{ task.title }}
    <span v-if="items.length > 1" class="count">{{ items.length }}</span>
  </div>
</template>

<style scoped>
.task-preview { width: 100%; height: 100%; }
</style>

• El componente recibe el arrastre como props: items (cada ítem arrastrado, empezando por el que se agarró), over, accepted, status, mode y to. Declara solo las que lees. Para las filas de una lista, el ítem de la lista es items[0].item.
• Pásalo tal cual. Cámbialo con un shallowRef, nunca con una ref profunda.

El slot del provider cambia de la misma forma, y tu componente ya no se posiciona a sí mismo:

v2

<DnDProvider>
  <RouterView />
  <template #preview>
    <MyOverlay />  <!-- moved itself with useDnDProvider().preview.position -->
  </template>
</DnDProvider>

v3

<DnDProvider>
  <RouterView />
  <template #overlay="{ items, over, accepted }">
    <MyOverlay :items="items" :over="over" :accepted="accepted" />
  </template>
</DnDProvider>

Una aparición que envolvía DragPreview en un <Transition> pasa a ser overlay-class con @starting-style: consulta levantar, inclinar, asentar.

Un drop que confirmas

v2

makeDroppable(el, {
  events: {
    onDrop: (e) =>
      new Promise<void | boolean>((resolve) => {
        if (!window.confirm('Drop here?')) return resolve(false); // keep dragging
        place(e.draggedItems);
        resolve();
      }),
  },
});

v3

makeDroppable(el, {
  onBeforeDrop: () => (window.confirm('Drop here?') ? 'accept' : 'continue'),
  onDrop: (e) => place(e.active.items),
});

Una lista pregunta de la misma forma, y una promesa te permite abrir un diálogo propio. El overlay espera donde se soltó hasta que la promesa se resuelve:

makeSortableList(el, {
  items: toRef(props.column, 'tasks'),
  group: 'board',
  // `ask` opens a dialog and resolves 'accept', 'continue' or 'reject'.
  onBeforeDrop: (e) => (e.sameList ? 'accept' : ask(e)),
});

Una zona que aceptaba solo la parte coincidente de una selección mixta (groupMatch: 'some'):

v2

makeDroppable(el, {
  groups: ['frontend'],
  groupMatch: 'some',
  events: {
    onDrop: (e) => place(e.draggedItems), // only the items of the group arrive
  },
});

v3

import type { DragItem } from '@vue-dnd-kit/core';

const fits = (item: DragItem) => item.type.length === 0 || item.type.includes('frontend');

makeDroppable(el, {
  accept: 'frontend',
  acceptMode: 'some',
  onBeforeDrop: (e) => e.active.items.filter(fits).map((item) => item.id), // the others fly back
  onDrop: (e) => place(e.active.items.filter(fits)), // `active.items` still lists every dragged item
});

Las listas lo hacen sin código: con acceptMode: 'some', aterrizan los ítems que acepta su group.put, y los demás vuelven a su sitio.

Escollos al actualizar

• Instala la v3 con su rango. ^3 en package.json: un npm update mantiene ^2 en la v2.
• Renderiza el borrador. Una lista renderiza los items que devuelve makeSortableList, no tu array. Si renderizas tu array, nada se mueve hasta el drop.
• No ordenes dos veces. Borra el código de suggestSort de las listas: una lista escribe cada drop en una ref items escribible después de su onDrop. Para aplicarlo tú, llama a e.preventDefault() y usa e.result.
• false rechaza el drop. En la v2, un onDrop que resolvía false mantenía el arrastre en curso. En la v3, devuelve 'continue' desde onBeforeDrop. Una promesa devuelta desde onDrop se ignora.
• Las listas solo comparten dentro de un group. Una lista sin él no intercambia con ninguna otra lista.
• Da a las filas el id como clave. :key="index" anima las filas equivocadas. Pasa también ids desde tus datos: un id por defecto es nuevo en cada instancia del componente.
• Sin <TransitionGroup>, sin transition en transform. La biblioteca mueve las filas ella misma, y los movimientos se animarían dos veces.
• Deshaz el apaño táctil. touch-action: none en un ítem entero impide que la página se desplace bajo el dedo; la v3 empieza los arrastres táctiles con una pulsación larga. Mantenlo en un asa que deba arrastrar enseguida, con activation: { touch: { distance: 4 } }.
• Quita los atributos obsoletos. La biblioteca pone el tabindex, el role y los aria-* que necesita y nunca sobrescribe los tuyos, así que un role o un aria-grabbed que hayan quedado se mantienen como los dejaste.
• Vuelve a dar estilo al overlay. .dnd-kit-preview ya no existe: da estilo a lo que hay dentro de [data-dnd-overlay='dragging'], nunca al transform de la caja. Dale width: 100%; height: 100% a la raíz de un componente de overlay, y saca <DragPreview /> de tus layouts.
• El desplazamiento automático está activado. Pasa :auto-scroll="false" donde la v2 nunca se desplazaba.
• Un rectángulo no necesita tecla. makeSelectionArea dibuja con una pulsación simple en su espacio vacío. Añade un modifier para conservar el Ctrl de la v2.
• Un provider, áreas dentro. Los ítems no pueden pasar de un provider a otro. Una página que usaba un provider por región para mantener separadas sus reglas necesita un provider y un makeDragArea por región.
• Dos argumentos. makeDraggable y makeDroppable reciben una ref y un objeto de opciones, sin payload.