CataUiDraggable

The CataUiDraggable component provides a flexible and intuitive drag-and-drop interface for sorting and transferring items between lists. It's built as a wrapper around vue.draggable, offering a simplified API while maintaining all the powerful features of the underlying library.

Draggable Item 1-1
Draggable Item 1-2
Draggable Item 1-3

Draggable Item 2-1
Draggable Item 2-2
Draggable Item 2-3

<CataUiDraggable
    animation="150"
    group="dragitems"
    item-key="id"
    v-model="draggableItems1">
    <template #item="{ element }">
        {{ element.label }}
    </template>
</CataUiDraggable>
<CataUiDraggable
    animation="150"
    group="dragitems"
    item-key="id"
    v-model="draggableItems2">
    <template #item="{ element }">
        {{ element.label }}
    </template>
</CataUiDraggable>

Tips

The CataUiDraggable component is a wrapper for vue.draggable. All props and events from vue.draggable are also available in this component.

For more information and advanced usage, see Vue Draggable

Props

Prop	Description	Type	Default	Required
animation	Animation speed in milliseconds	Number	150	false
forceFallback	Force the fallback option even if native HTML5 drag & drop is available	Boolean	true	false
ghost-class	Class name for the drop placeholder	String	'ghost'	false
group	Group name for the lists that should be able to share items	String		false
item-key	Unique identifier field name in your items	String	'id'	false
revertOnSpill	Revert drag operation when the item is dropped outside of a valid list	Boolean	true	false
tag	HTML tag used for the list container	String	'ul'	false
v-model	An array of draggable elements	Array		true

Events

Event	Description	Parameters
end	Triggered when a drag operation ends	None
start	Triggered when a drag operation starts	None
unchoose	Triggered when an item is no longer being dragged	None

Slots

Slot	Description	Props
item	Template for each draggable item	{ element }

Example Usage

Here's a complete example of how to use CataUiDraggable with two connected lists:

<script setup>
import { ref } from 'vue';

// Data structure for draggable items
const draggableItems1 = ref([
    {
        id: 11,        // Required unique identifier matching the item-key prop
        label: 'Draggable Item 1-1'
    },
    {
        id: 12,
        label: 'Draggable Item 1-2'
    },
    {
        id: 13,
        label: 'Draggable Item 1-3'
    },
]);

const draggableItems2 = ref([
    {
        id: 21,
        label: 'Draggable Item 2-1'
    },
    {
        id: 22,
        label: 'Draggable Item 2-2'
    },
    {
        id: 23,
        label: 'Draggable Item 2-3'
    },
]);

// Optional: Track when the drag operation starts and ends
function onDragStart() {
    console.log('Drag operation started');
}

function onDragEnd() {
    console.log('Drag operation ended');
}
</script>

<template>
    <div class="lists-container">
        <!-- First draggable list -->
        <CataUiDraggable
            animation="150"
            group="dragitems"
            item-key="id"
            v-model="draggableItems1"
            @start="onDragStart"
            @end="onDragEnd">
            <template #item="{ element }">
                {{ element.label }}
            </template>
        </CataUiDraggable>
        
        <!-- Second draggable list that shares the same group -->
        <CataUiDraggable
            animation="150"
            group="dragitems"
            item-key="id"
            v-model="draggableItems2">
            <template #item="{ element }">
                {{ element.label }}
            </template>
        </CataUiDraggable>    </div>
</template>

<style scoped>
.lists-container {
    display: flex;
    gap: 20px;
}
</style>

Advanced Usage Notes

Multiple Connected Lists: Use the same group prop value to allow items to be dragged between lists.

One-Way Transfer: To create a one-way transfer between lists, use an object for the group prop:

<!-- Source list (can only move items from) -->
<CataUiDraggable :group="{ name: 'items', pull: 'clone', put: false }" ... />

<!-- Target list (can only receive items) -->
<CataUiDraggable :group="{ name: 'items', pull: false, put: true }" ... />

Item Validation: Use the @add event to validate items before they're added to a list.
Custom Drag Handle: For more complex items, use the handle prop to specify a CSS selector for the drag handle.