Sortable

Reorder elements in a list or across multiple lists.

Usage

The Sortable class allows you to reorder elements in a list or across multiple lists. A sortable element is both Droppable and Draggable, which means you can drag it and drop it to reorder.

First, create a DragDropManager instance and use it to create sortable items:

Multiple Lists

You can create multiple sortable lists by assigning sortable items to different groups:

const list1 = ['Item 1', 'Item 2'];
const list2 = ['Item 3', 'Item 4'];

// First list
list1.forEach((item, index) => {
  new Sortable({
    id: item,
    index,
    group: 'list1', // Assign to first group
    element: createItemElement(item),
  }, manager);
});

// Second list
list2.forEach((item, index) => {
  new Sortable({
    id: item,
    index,
    group: 'list2', // Assign to second group
    element: createItemElement(item),
  }, manager);
});

Drag Handles

By default, the entire sortable element can be used to initiate dragging. You can restrict dragging to a specific handle element:

const element = document.createElement('li');
const handle = document.createElement('div');
handle.classList.add('handle');

element.appendChild(handle);

new Sortable({
  id: 'item-1',
  index: 0,
  element,
  handle, // Only allow dragging from the handle
}, manager);

Animations

Sortable items automatically animate when their position changes. You can customize the animation through the transition option:

new Sortable({
  id: 'item-1',
  index: 0,
  transition: {
    duration: 250, // Animation duration in ms
    easing: 'cubic-bezier(0.25, 1, 0.5, 1)', // Animation easing
    idle: false, // Whether to animate when no drag is in progress
  }
}, manager);

Optimistic Sorting

By default, every Sortable instance registers the OptimisticSortingPlugin. This plugin optimistically reorders DOM elements during a drag operation so that the UI feels responsive — without requiring your framework to re-render on every dragover event.

How it works

When you drag a sortable item over another sortable item, the plugin:

1. Physically moves the DOM elements to reflect the new order.
2. Updates the index (and group, for multi-list scenarios) on each affected Sortable instance.
3. Sets the drop target to the drag source itself by calling manager.actions.setDropTarget(source.id).

Step 3 has an important consequence: during a drag, source and target on the operation will refer to the same element. This also means that isDragSource and isDropTarget will both be true on the dragged item.

Tracking position changes

Since source and target are the same, you cannot compare their IDs to determine what moved. Instead, use the sortable-specific properties available on the source:

Property	Description
index	The current position of the item (updated by the plugin as it moves)
initialIndex	The position the item was in when the drag started
group	The current group the item belongs to
initialGroup	The group the item was in when the drag started

Preventing optimistic sorting for a single event

If you call event.preventDefault() in a dragover handler, the OptimisticSortingPlugin will skip the optimistic update for that particular event. This is useful when you want to handle certain moves yourself (for example, to prevent items from being dragged into a specific group) while still letting the plugin handle the rest:

manager.monitor.addEventListener('dragover', (event) => {
  const {source, target} = event.operation;

  if (shouldPreventMove(source, target)) {
    event.preventDefault(); // Optimistic sorting will not run for this event
  }
});

Disabling optimistic sorting

If you prefer to manage sorting entirely in your application state (for example, by handling every dragover event), you can disable optimistic sorting by omitting the OptimisticSortingPlugin from the plugins array:

import {SortableKeyboardPlugin} from '@dnd-kit/dom/sortable';

new Sortable({
  id: 'item-1',
  index: 0,
  element,
  plugins: [SortableKeyboardPlugin], // No OptimisticSortingPlugin
}, manager);

Without optimistic sorting, source and target will be different elements during drag, and you can use their IDs directly. However, you will need to handle reordering in your dragover listener for smooth visual feedback.

Managing state without the move helper

The move helper from @dnd-kit/helpers is 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 sortable properties and the isSortable type guard.

Single list

With optimistic sorting enabled (the default), you only need to handle the dragend event. The isSortable type guard narrows the source to expose initialIndex and index:

import {isSortable} from '@dnd-kit/dom/sortable';

manager.monitor.addEventListener('dragend', (event) => {
  if (event.canceled) return;

  const {source} = event.operation;

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

    if (initialIndex !== index) {
      // Reorder your data: move the item from initialIndex to index
      const newItems = [...items];
      const [removed] = newItems.splice(initialIndex, 1);
      newItems.splice(index, 0, removed);
      items = newItems;
    }
  }
});

Multiple lists

For multiple lists, use initialGroup and group to detect whether the item stayed in the same list or moved to a different one:

manager.monitor.addEventListener('dragend', (event) => {
  if (event.canceled) return;

  const {source} = event.operation;

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

    if (initialGroup === group) {
      // Same group: reorder within the list
      const groupItems = [...items[group]];
      const [removed] = groupItems.splice(initialIndex, 1);
      groupItems.splice(index, 0, removed);
      items = {...items, [group]: groupItems};
    } else {
      // Cross-group transfer
      const sourceItems = [...items[initialGroup]];
      const [removed] = sourceItems.splice(initialIndex, 1);
      const targetItems = [...items[group]];
      targetItems.splice(index, 0, removed);
      items = {...items, [initialGroup]: sourceItems, [group]: targetItems};
    }
  }
});

Type Guards

@dnd-kit/dom/sortable exports two type guards to help you work with sortable drag operations.

isSortable

Checks whether a Draggable or Droppable instance is a sortable element. If it returns true, the type is narrowed to expose sortable-specific properties like index, initialIndex, group, and initialGroup.

import {isSortable} from '@dnd-kit/dom/sortable';

const {source} = event.operation;

if (isSortable(source)) {
  console.log(source.index);        // number
  console.log(source.initialIndex);  // number
  console.log(source.group);         // string | number | undefined
  console.log(source.initialGroup);  // string | number | undefined
}

isSortableOperation

Checks whether both source and target of a drag operation are sortable elements. This is useful when you want to narrow the entire operation at once:

import {isSortableOperation} from '@dnd-kit/dom/sortable';

const {operation} = event;

if (isSortableOperation(operation)) {
  // Both source and target are narrowed to sortable types
  console.log(operation.source.initialIndex);
  console.log(operation.target.index);
}

Both type guards are also available from framework-specific packages:

• @dnd-kit/react/sortable
• @dnd-kit/vue/sortable
• @dnd-kit/svelte/sortable
• @dnd-kit/solid/sortable

API Reference

Arguments

The Sortable class accepts the following arguments:

id · string | number · required

A unique identifier for this sortable item within the drag and drop manager.

index · number · required

The position of this item within its sortable group.

element · Element

The DOM element to make sortable. While not required in the constructor, it must be set to enable sorting.

group · string | number

Optionally assign this item to a group. Items can only be sorted within their group.

handle · Element

Optionally specify a drag handle element. If not provided, the entire element will be draggable.

target · Element

Optionally specify a different element to use as the drop target. By default, uses the main element.

transition · SortableTransition | null

Configure the animation when items are reordered:

interface SortableTransition {
  duration?: number; // Duration in ms (default: 250)
  easing?: string;  // CSS easing function (default: cubic-bezier)
  idle?: boolean;   // Animate when not dragging (default: false)
}

disabled · boolean | SortableDisabled

Set to true to temporarily disable sorting for this item. Pass an object to disable dragging and dropping independently:

interface SortableDisabled {
  draggable?: boolean; // Prevent this item from being dragged
  droppable?: boolean; // Prevent other items from being dropped on this one
}

type · string | number | Symbol

Optionally restrict which types of items can be sorted together.

accept · Type | Type[] | ((source: Draggable) => boolean)

Restrict which draggables can be dropped on this sortable item. Pass a single type, an array of types, or a predicate that receives the draggable and returns true to accept it.

modifiers · Modifier[]

An array of modifiers to customize drag behavior.

sensors · Sensors[]

An array of sensors to detect drag interactions.

data · {[key: string]: any}

Optional data to associate with this sortable item, available in event handlers.

Properties

The Sortable instance provides these key properties:

• index: The current position in the list
• group: The assigned group identifier
• isDragging: Whether this item is currently being dragged
• isDropTarget: Whether this item is currently a drop target
• disabled: Whether sorting is disabled for this item. Returns a boolean when dragging and dropping share the same state, or a {draggable, droppable} object when they differ
• element: The main DOM element
• target: The drop target element (if different from main element)

Methods

• register(): Register this sortable item with the manager
• unregister(): Remove this item from the manager
• destroy(): Clean up this sortable instance
• accepts(draggable): Check if this item accepts a draggable
• refreshShape(): Recalculate the item’s dimensions