UIDraggableElement

UIDraggableElement

A draggable element component designed for builder interfaces, allowing users to drag and drop elements within a predefined area. Commonly used for creating visual editors, form builders, and customizable layouts.

<template>
  <UIDraggableElement
    id="draggable-element"
    label="Element Label"
    :icon="IconComponent"
    :disabled="false"
    :draggable="true"
    @dragstart="handleDragStart"
    @dragend="handleDragEnd"
  >
    <template #icon>
      <CustomIcon class="w-8 h-8" />
    </template>

    <template #content>
      <div class="p-2">
        Additional content can be placed here
      </div>
    </template>
  </UIDraggableElement>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CustomIcon } from '@/components/icons'

const handleDragStart = (event) => {
  // Set data transfer properties
  event.dataTransfer.setData('element-id', 'draggable-element')
}

const handleDragEnd = () => {
  // Handle drag end actions
  console.log('Element dragging ended')
}
</script>

Props

• id (string, required): Unique identifier for the element
• label (string): Label text for the element
• icon (Component): Icon component to display
• disabled (boolean): Whether the element is disabled
• draggable (boolean): Enable/disable drag functionality
• data (object): Data to be transferred during drag operations
• handle (string): CSS selector for the drag handle
• group (string): Group identifier for drag targets

Events

• dragstart: Emitted when dragging starts
• dragend: Emitted when dragging ends
• drop: Emitted when the element is dropped
• click: Emitted when the element is clicked

Slots

• icon: Custom icon content
• content: Custom content for the element
• handle: Custom drag handle content

Usage Examples

1. Basic Draggable Element:

<template>
  <UIDraggableElement
    id="basic-element"
    label="Drag Me"
  />
</template>

2. With Custom Data:

<template>
  <UIDraggableElement
    id="form-field"
    label="Text Input"
    :data="{
      type: 'input',
      field: 'text',
      config: { required: true }
    }"
    @dragstart="handleDragStart"
  />
</template>

<script setup>
const handleDragStart = (event) => {
  console.log('Dragging element with data:', event.data)
}
</script>

3. With Custom Handle:

<template>
  <UIDraggableElement
    id="custom-handle-element"
    label="Custom Handle"
    handle=".drag-handle"
  >
    <template #handle>
      <div class="drag-handle">
        <DragIcon class="w-4 h-4" />
      </div>
    </template>
    <template #content>
      <div class="p-4">
        This content is not draggable directly,
        use the handle.
      </div>
    </template>
  </UIDraggableElement>
</template>

4. Disabled State:

<template>
  <UIDraggableElement
    id="disabled-element"
    label="Cannot Drag"
    :disabled="true"
  />
</template>

Best Practices

1. Drag and Drop UX:

   • Provide clear visual feedback during drag
   • Use appropriate cursors for drag states
   • Consider distance thresholds for drag initiation
   • Handle edge cases like invalid drop areas

2. Performance:

   • Optimize drag events for smooth interaction
   • Use lightweight data in drag payloads
   • Consider debouncing position updates
   • Handle large collections efficiently

3. Accessibility:

   • Provide keyboard alternatives for drag operations
   • Include ARIA attributes for drag states
   • Ensure sufficient color contrast
   • Add descriptive instructions

4. Integration:

   • Define clear drop zones
   • Handle multi-element selection
   • Provide undo/redo capabilities
   • Implement preview of drop results