Docs/API

makeSortableItem

Registers a row of a sortable list or tree — it drags, makes room and lands in its slot.

function makeSortableItem<TData = unknown>(  target: MaybeElementRef,  options: SortableItemOptions<TData>,): SortableItemReturn;

Makes an element a row of a sortable list or tree: it drags, makes room and lands in its slot. Call it in a component rendered inside the one that called makeSortableList (or makeSortableTree); of several lists made there, the row joins the innermost one whose element holds it. Identify the row with item (keyed by the list's getKey, item.id by default) or id.

const el = useTemplateRef<HTMLElement>('el');
const { isPlaceholder, index } = makeSortableItem(el, { item: () => props.task, handle: '.grip' });

See Sortable lists.

Live Drag a row by its grip: the checkbox still works

Loading the demo…

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

<template>
  <DnDProvider>
    <TodoList />
  </DnDProvider>
</template>

Options

Pass id or item (id wins when both are given). Sortable keys must come from the data: an automatic id would change whenever the component is recreated (moved to another list, recycled by a virtual list), and the drag would lose the item.

Options but canDrag take a value, a ref or a getter (overlay, dropAnimation: a value or a ref) and mean what they mean on makeDraggable. There is no keyboardMode: the keyboard moves a sortable item by slots.

id?

Keyvalue · ref · getter

Key of the item in its list. A getter keeps it current in virtual lists.

item?

unknownvalue · ref · getter

The item this element renders, e.g. () => props.task. Its key comes from the owning list's (or tree's) getKey, by default item.id.

overlay?

Componentvalue · ref

Overlay component for this item; wins over the list's overlay. A ref switched mid-drag swaps it at once.

dropAnimation?

DropAnimationvalue · ref

How the overlay lands when a drag of this item ends; wins over the list's dropAnimation. Read at the drop.

modifiers?

Modifier[]value · ref · getter

Modifiers for drags of this item, after the provider's; win over the list's modifiers.

axis?

'x' | 'y'value · ref · getter

Locks drags of this item to one axis ('x', 'y'); wins over the list's axis.

handle?

MaybeElement | stringvalue · ref · getter

Element or selector inside the item that starts the drag (and gets the attributes).

disabled?

booleanvalue · ref · getter

true: the item can't be dragged (as every item of a disabled list).

type?

string | string[]value · ref · getter

Its type or types, for group.put rules and drop targets' accept. Default: the name of its list's group.

data?

TDatavalue · ref · getter

Anything the drag should carry: events and drop targets read it as active.data.

label?

stringvalue · ref · getter

What people call the item: screen reader texts say it instead of its key (Picked up Tomato at position 2 of 5 in Garden). Events carry it as active.label and in items.

activation?

ActivationOptionsvalue · ref · getter

Overrides its list's (or tree's) activation and the provider's. Read when a press starts.

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

Extra gate, e.g. drag only while a key is held.

attributes?

booleanvalue · ref · getter

Set role/tabindex/aria-* attributes (default true), never overriding the user's own. Live: turning it off removes what the library set.

native?

boolean | NativeDragOptionsvalue · ref · getter

A mouse drag of it is the browser's own drag, which can leave the page (see DraggableOptions.native). It carries the item too: the lists of its group in another window of the app take it, and when one does, it leaves this list ('move').

Returns

What makeSortableItem returns.

isDragging

ComputedRef<boolean>

This item is being dragged (also true for the other items of a multi-drag), or its overlay is still landing.

isPlaceholder

ComputedRef<boolean>

This element is a slot a dragged item will land in: the active item's, and in multi-drag 'group' mode the slots of the items travelling with it.

selected

WritableComputedRef<boolean>

It is in the provider's selection: a drag of one selected item carries them all. Set it to select or deselect.

indicator

ComputedRef<SortableIndicator | null>

Indicator mode: the list's indicator while it is attached to this item, null otherwise. side says where the line goes; in trees depth and parentKey say where the drop lands (side: 'inside': into this item).

index

ComputedRef<number>

Index in the rendered draft, -1 when unknown.