createSortable

Headless ordered-list primitive that owns a registry of value-bearing tickets and exposes move, swap, and reorder mutations. Pure logic — no DnD, no keyboard, no DOM — so consumers can drive it from any input modality.

Usage

createSortable extends createModel with mutation primitives over the canonical order. Drag-and-drop wiring composes with useDragDrop; keyboard reorder composes with useVirtualFocus. Consumers can drive sortable from buttons, gestures, server reconciliation, or undo/redo by calling its mutation methods.

import { createSortable } from '@vuetify/v0'

import type { SortableTicketInput } from '@vuetify/v0'

interface Task {
  id: number
  label: string
}

interface TaskTicket extends SortableTicketInput {
  value: Task
}

const sortable = createSortable<TaskTicket>()

const [a, b, c] = sortable.onboard([
  { value: { id: 1, label: 'Cut alpha' } },
  { value: { id: 2, label: 'Ship docs' } },
  { value: { id: 3, label: 'Tweet' } },
])

sortable.move(a.id, 2)
sortable.swap(a.id, b.id)
sortable.reorder([b.id, a.id, c.id])

Architecture

createSortable extends createModel, which extends createRegistry. All methods inherited from those layers are available unchanged, except on and off — those are extended with typed overloads for the move:ticket event. See createModel and createRegistry for the full inherited surface.

The composable adds four things on top of createModel:

Reactivity

createSortable’s surface is mostly imperative — move, swap, and reorder mutate the registry and the reactive updates flow downstream through registry events. The composable bakes in events: true so move:ticket and the standard registry events fire without extra setup.

Examples

Recipes

Disabling reorder

disabled works at two scopes. Root (createSortable({ disabled })) no-ops move, swap, and reorder for the whole list. Per-ticket (register({ value, disabled: true })) no-ops move and swap for that ticket. reorder bypasses per-ticket disabled — it’s a bulk operation declaring the canonical order; if you want disabled tickets pinned, exclude their ids from the array. Registration is never gated.

const sortable = createSortable<Todo>({
  disabled: toRef(() => isReadOnlyMode.value),
})

sortable.move(id, 0)   // no-op when disabled.value === true

Server-reconciled order

reorder accepts a strict permutation of currently-registered ids. Use it to apply an authoritative order from the backend without diffing positions yourself.

const sortable = createSortable<Todo>()
const order = await fetchOrder()       // ID[] from backend
sortable.reorder(order)

Reactive snapshot for templates

useProxyRegistry returns a reactive { keys, values, entries, size } snapshot driven by registry events. Because createSortable bakes in events: true, you do not pass it explicitly.

const sortable = createSortable<Todo>()
const proxy = useProxyRegistry(sortable)

// proxy.keys, proxy.values, proxy.entries, proxy.size all track moves

Pair with useDragDrop

Wire useDragDrop’s onDrop callback to sortable.move to translate pointer or keyboard drags into reorder mutations. The headless contract keeps the two primitives independent — sortable owns order, drag-drop owns input.

const sortable = createSortable<Todo>()
const dnd = useDragDrop()

dnd.zones.register({
  el: containerEl,
  accept: ['todo'],
  onDrop: (drag, position) => {
    if (drag.type === 'todo') sortable.move(drag.id, position.index ?? 0)
  },
})

A first-class useSortableDnD adapter is on the roadmap; until then, wire useDragDrop’s callbacks to sortable.move directly.

FAQ