API Reference

Directives

x-drag-context

Marks a container whose x-drag-item descendants can be reordered. Items of nested contexts belong to the nested context.

<ul x-drag-context>…</ul>
<ul x-drag-context="{ group: 'tasks', id: 'todo', disabled: full }">…</ul>
<ul x-drag-context.group.tasks>…</ul>

The expression is optional. When present it must evaluate to an object; it is re-evaluated every time the package checks the context, so it is reactive. Expression values win over attributes, which win over the .group modifier.

See Connected Containers and Configuration and Translations.

x-drag-item

<li x-drag-item="{{ $task->id }}" wire:key="task-{{ $task->id }}" data-drag-label="{{ $task->title }}">…</li>

The expression is the item's id: {{ $item->id }}, '{{ $uuid }}', item.id. It is reported as itemId and in orderedIds.

Pointer drags never start from input, textarea, select, option, or contenteditable elements. Keyboard handling only applies when the item element itself has focus.

Attributes set by the package

Elements the package creates: the live region ([data-drag-live-region]), the hidden instructions ([data-drag-instructions]), the floating copy ([data-drag-ghost]), and the drop indicator ([data-drag-indicator]). See Styling.

Events

Dispatched on context elements; they do not bubble. Details are JSON-safe; itemElement, fromElement, and toElement are available as non-enumerable properties. Indices are zero-based.

orderedIds is the order of the context the event is dispatched on. reason is one of escape, blur, outside, not-allowed, rejected, pointercancel, or removed.

See Events and Lifecycle for when each fires and examples.

Alpine magic

$dragRevert( itemId )

Reverts the item's most recent recorded move. Returns true if anything moved back.

@drag:end="$wire.moveCard( $event.detail ).then( ( ok ) => ok || $dragRevert( $event.detail.itemId ) )"

JavaScript API

The default export, also available as window.LivewireDragAndDrop:

import LivewireDragAndDrop from '@artisanpack-ui/livewire-drag-and-drop';

LivewireDragAndDrop( Alpine )

Alpine plugin that registers x-drag-context, x-drag-item, and $dragRevert. Use it as Alpine.plugin( LivewireDragAndDrop ) or call it directly. It is also called automatically on alpine:init, and calling it more than once on the same Alpine instance does nothing.

LivewireDragAndDrop.configure( options )

Merges global settings and returns the resulting settings object.

LivewireDragAndDrop.revert( moveId )

Reverts a committed move by its moveId (from drag:end). Returns true if anything moved back. Dispatches drag:revert and announces the reverted message. Later recorded moves of the same item are discarded.

LivewireDragAndDrop.revertItem( itemId )

Reverts the item's most recent recorded move. Same as $dragRevert.

LivewireDragAndDrop.itemId( element )

Returns the id of an x-drag-item element, or null.

LivewireDragAndDrop.registerLivewireHooks( Livewire )

Registers the Livewire morphed hook that re-applies ARIA attributes, cancels drags whose item was removed, and restores focus after keyboard drops. It is called automatically on livewire:init (and immediately if window.Livewire already exists when the package loads), so you only need it if Livewire is not on window. Calling it more than once does nothing.

Named exports

For compatibility with 2.0.1, the module also has named exports:

import { registerDirectives, registerLivewireHooks } from '@artisanpack-ui/livewire-drag-and-drop';

registerDirectives is the same function as the default export; registerLivewireHooks is LivewireDragAndDrop.registerLivewireHooks.

Builds