useSortable

Create sortable elements with the useSortable composable.

Usage

The useSortable composable combines draggable and droppable behavior with sorting logic. Import it from @dnd-kit/vue/sortable.

When passing props to useSortable, wrap reactive values in computed() to maintain reactivity. Plain values like props.id are read once during setup and won’t update.

Without the move helper

The example above uses the move helper from @dnd-kit/helpers, a convenience function that takes your items and a drag event and returns a new array with the item moved to its new position. It supports flat arrays and grouped records, handles canceled drags, and works with optimistic sorting out of the box.

If you need more control over state updates, you can manage state manually using the isSortable type guard and the sortable properties (initialIndex, index).

With optimistic sorting enabled (the default), you only need to handle the dragEnd event:

<script setup lang="ts">
import { ref } from 'vue';
import { DragDropProvider, type DragEndEvent } from '@dnd-kit/vue';
import { isSortable } from '@dnd-kit/vue/sortable';
import SortableItem from './SortableItem.vue';

const items = ref([1, 2, 3, 4]);

function onDragEnd(event: DragEndEvent) {
  if (event.canceled) return;

  const { source } = event.operation;

  if (isSortable(source)) {
    const { initialIndex, index } = source;

    if (initialIndex !== index) {
      const newItems = [...items.value];
      const [removed] = newItems.splice(initialIndex, 1);
      newItems.splice(index, 0, removed);
      items.value = newItems;
    }
  }
}
</script>

<template>
  <DragDropProvider @dragEnd="onDragEnd">
    <ul class="list">
      <SortableItem
        v-for="(id, index) in items"
        :key="id"
        :id="id"
        :index="index"
      />
    </ul>
  </DragDropProvider>
</template>

You can call event.preventDefault() in a @dragOver handler to prevent the OptimisticSortingPlugin from optimistically updating for that specific event. This is useful when you want to conditionally block certain moves.

Learn more about optimistic sorting, type guards, and manual state management in the Sortable concepts page.

Input

All input properties accept plain values or Vue refs/getters (MaybeRefOrGetter).

id · MaybeRefOrGetter<UniqueIdentifier> · required

A unique identifier for this sortable instance.

index · MaybeRefOrGetter<number> · required

The current index of this item in the sorted list.

element · MaybeRefOrGetter<HTMLElement | null> · required

A template ref pointing to the sortable element.

group · MaybeRefOrGetter<string>

The group this sortable belongs to. Used for sorting across multiple lists.

handle · MaybeRefOrGetter<HTMLElement | null>

A template ref for a drag handle.

accept · MaybeRefOrGetter<string | string[]>

The types of draggable elements this sortable accepts.

type · MaybeRefOrGetter<string>

The type of this sortable element.

plugins · MaybeRefOrGetter<PluginDescriptor[]>

An array of plugin descriptors for per-entity plugin configuration. Use Plugin.configure() to create descriptors. For example, Feedback.configure({ feedback: 'clone' }).

transition · MaybeRefOrGetter<SortableTransition>

Animation transition configuration for sort operations.

modifiers · MaybeRefOrGetter<Modifier[]>

Modifiers to apply to this sortable instance.

sensors · MaybeRefOrGetter<Sensor[]>

Sensors to use for this sortable instance.

collisionDetector · MaybeRefOrGetter<CollisionDetector>

A custom collision detection algorithm.

collisionPriority · MaybeRefOrGetter<number>

The collision priority of this sortable element. Higher values take precedence when multiple droppable elements overlap.

disabled · MaybeRefOrGetter<boolean>

Whether the sortable is disabled.

data · MaybeRefOrGetter<Data>

Custom data to attach to this sortable instance.

Output

isDragging · ComputedRef<boolean>

Whether this element is currently being dragged.

isDropping · ComputedRef<boolean>

Whether this element is in the process of being dropped.

isDragSource · ComputedRef<boolean>

Whether this element is the source of the current drag operation.

isDropTarget · ComputedRef<boolean>

Whether this element is currently a drop target.

sortable · ShallowReadonly<Ref<Sortable>>

The underlying Sortable instance.