Sortable

Headless Sortable; covers React Aria useDraggableCollection, ARIA APG drag reordering.

API

createSortable

Create an SSR-safe sortable coordinator for lists, grids, and trees.

function createSortable(options: SortableOptions = {}): SortableController

useSortable

Create a sortable coordinator disposed with the current Vue effect scope.

function useSortable(options: SortableOptions = {}): SortableController

readOrientation

Resolve the closed orientation union without accepting mistyped JavaScript.

function readOrientation(value: SortableOptions["orientation"]): SortableOrientation

readDirection

Resolve the closed direction union without accepting mistyped JavaScript.

function readDirection(value: SortableOptions["direction"]): SortableDirection

readColumns

Resolve a positive integer column count for grid arrow-key geometry.

function readColumns(value: SortableOptions["columns"]): number

edgesFor

Drop edges one item target resolves for an orientation.

function edgesFor(orientation: SortableOrientation, nesting: boolean): readonly DropEdge[]

edgeForPosition

Map a logical position back onto the physical edge for an orientation.

function edgeForPosition( position: SortablePosition, orientation: SortableOrientation, direction: SortableDirection, ): DropEdge

createSortableEvent

Build a frozen lifecycle snapshot for sortable callbacks.

function createSortableEvent<Type extends SortableEventType>( type: Type, pointerType: DragPointerType, key: string, fromIndex: number, toIndex: number, overKey: string | null, position: SortablePosition | null, originalEvent: Event | null, ): SortableEvent<Type>

positionForEdge

Map a physical drop edge onto the logical position for an orientation.

function positionForEdge( edge: DropEdge, orientation: SortableOrientation, direction: SortableDirection, ): SortablePosition

computeToIndex

Compute the insertion index for moving fromIndex relative to overIndex. "inside" moves report the receiving item's index unchanged.

function computeToIndex( fromIndex: number, overIndex: number, position: SortablePosition, ): number

keyboardDelta

Signed index step for one arrow key, or null when the key is not owned.

function keyboardDelta( key: string, orientation: SortableOrientation, direction: SortableDirection, columns: number, ): number | null

dispatchSortableEvent

Dispatch one lifecycle snapshot to the matching consumer callback.

function dispatchSortableEvent(options: SortableOptions, event: SortableEvent): void

projectDragContext

Project a drag-and-drop context onto sortable indexes and positions.

function projectDragContext( keys: readonly string[], orientation: SortableOrientation, direction: SortableDirection, dragContext: DragContextSlice, ): SortableProjection

sortableContextFor

Build the sortable announcement context for one drag announcement phase.

function sortableContextFor( phase: "cancel" | "drop" | "grab" | "move", dragContext: AnnouncementSlice, projection: SortableProjection, count: number, originIndex: number | null, ): SortableAnnouncementContext

defaultSortableAnnouncements

Built-in English announcement builders; consumers override to localize.

const defaultSortableAnnouncements: Required<SortableAnnouncements>

handleSortableKeydown

Handle one keydown from an item: grab, move, nest, drop, or cancel.

function handleSortableKeydown( host: SortableKeyboardHost, event: KeyboardEvent, key: string, ): void

cancelSortableKeyboard

Cancel an owned keyboard sort from focus loss or programmatic teardown.

function cancelSortableKeyboard(host: SortableKeyboardHost, event: Event | null): boolean

Behavior

Normative state × input → outcome table for @vizejs/ui/sortable. Every row is exercised by src/families/interaction/sortable/sortable*.test.ts; compile-only assertions live in src/families/interaction/sortable/sortable.types.test-d.ts.

Accessibility and layout obligations

Every item host must be keyboard focusable so pointer sorting has an Enter-grab, arrow-move, Enter-drop equivalent, and every phase speaks through the underlying drag-and-drop live region with injectable, localizable builders. Grid and horizontal arrow keys resolve against the configured writing direction so RTL layouts move logically. The primitive is headless: it assigns no role or style, and consumers render placeholder and indicator geometry from the reactive indicator state. Nested trees compose this family with the drag-and-drop core's innermost-target ownership; "inside" previews and commits carry the receiving item so consumers re-parent their own model.