Search documentation of phoenix_kit

# PhoenixKitWeb.Components.Core.DraggableList (phoenix_kit v1.7.87)

Copy Markdown View Source

A reusable drag-and-drop sortable component supporting both grid and list layouts.

Uses SortableJS (auto-loaded from CDN) to enable drag-and-drop reordering of items. The component sends a LiveView event when items are reordered.

## Design Philosophy

This component provides minimal opinionated styling - it handles drag-drop behavior while you control the appearance through classes and slot content.

## Usage - Grid Layout (default)

Perfect for image galleries, card grids, etc:

    <.draggable_list
      id="post-images"
      items={@images}
      on_reorder="reorder_images"
      cols={4}
    >
      <:item :let={img}>
        <img src={img.url} class="w-full aspect-square object-cover rounded" />
      </:item>
      <:add_button>
        <button phx-click="add_image" class="btn">Add</button>
      </:add_button>
    </.draggable_list>

## Usage - List Layout

Perfect for column selectors, ordered lists, etc:

    <.draggable_list
      id="table-columns"
      items={@columns}
      on_reorder="reorder_columns"
      layout={:list}
      item_class="flex items-center p-3 bg-base-100 border rounded-lg hover:bg-base-200"
    >
      <:item :let={col}>
        <div class="mr-3 text-base-content/40">
          <.icon name="hero-bars-3" class="w-5 h-5" />
        </div>
        <span class="flex-1 font-medium">{col.label}</span>
        <button phx-click="remove_column" phx-value-id={col.id} class="btn btn-ghost btn-xs">
          <.icon name="hero-x-mark" class="w-4 h-4" />
        </button>
      </:item>
    </.draggable_list>

## Event Handler

The `on_reorder` event receives `%{"ordered_ids" => [id1, id2, ...]}` with the new order:

    def handle_event("reorder_items", %{"ordered_ids" => ordered_ids}, socket) do
      # ordered_ids is a list of item IDs in the new order
      {:noreply, socket}
    end

## Summary

### Functions

draggable_list(assigns)

## Functions

# draggable_list(assigns)

## Attributes

- `id` (`:string`) (required) - Unique ID for the container.
- `items` (`:list`) (required) - List of items to display.
- `item_id` (`:any`) - Function to extract ID from item, defaults to &(&1.id). Defaults to `nil`.
- `on_reorder` (`:string`) (required) - Event name to send on reorder.
- `layout` (`:atom`) - Layout mode. Defaults to `:grid`. Must be one of `:grid`, or `:list`.
- `cols` (`:integer`) - Number of grid columns (only for layout={:grid}). Defaults to `4`.
- `gap` (`:string`) - Gap between items (Tailwind class). Defaults to `"gap-2"`.
- `class` (`:string`) - Additional CSS classes for the container. Defaults to `""`.
- `item_class` (`:string`) - Additional CSS classes for each item wrapper. Defaults to `""`.

## Slots

- `item` (required) - Slot to render each item, receives the item as let.
- `add_button` - Optional slot for add button at end of container.