Drag & Drop
Svelte 5 attachment-based sortable lists with a shared ghost and drop indicator. Cross-list moves use onRemove / onReceive. OS file drops use the DropZone component.
import { dndList, dndItem, DndGhost, DndIndicator } from "phoundry-ui";Sortable list
Loading interactive example…
View source
<script lang="ts"> import { dndList, dndItem, type DndItemData } from "phoundry-ui";
interface ListItem extends DndItemData { id: string; label: string; }
let items = $state<ListItem[]>([ { id: "1", label: "First item" }, { id: "2", label: "Second item" }, { id: "3", label: "Third item" }, { id: "4", label: "Fourth item" }, { id: "5", label: "Fifth item" }, ]);
const sortableDemo = $derived( dndList({ id: "demo-list", axis: "y", showZoneIndicator: false, onReorder(fromIndex, toIndex) { const moved = items.splice(fromIndex, 1)[0]; items.splice(toIndex, 0, moved); items = [...items]; }, }), );</script>
<div class="space-y-2"> <div {@attach sortableDemo} class="space-y-1"> {#each items as item (item.id)} <div {@attach dndItem({ id: item.id, data: item })} class="cursor-grab rounded border border-border-muted bg-surface-raised px-3 py-2 text-xs text-txt-primary transition-colors select-none hover:border-border-default" > {item.label} </div> {/each} </div> <p class="text-[11px] text-txt-tertiary"> Drag to reorder. Import bundled styles (<code >phoundry-ui/styles/components.css</code >) so <code>dnd.css</code> applies (grab cursor, dragging opacity, zone hints). </p></div>Cross-list transfer
Loading interactive example…
View source
<script lang="ts"> import { dndList, dndItem, type DndItemData } from "phoundry-ui";
interface ListItem extends DndItemData { id: string; label: string; }
let itemsA = $state<ListItem[]>([ { id: "a1", label: "Alpha" }, { id: "a2", label: "Beta" }, ]);
let itemsB = $state<ListItem[]>([ { id: "b1", label: "Gamma" }, { id: "b2", label: "Delta" }, ]);
let pendingCross: { item: ListItem; fromListId: string } | null = null;
const listAAttach = $derived( dndList({ id: "cross-a", axis: "y", acceptFrom: ["cross-b"], showZoneIndicator: false, onReorder(fromIndex, toIndex) { const moved = itemsA.splice(fromIndex, 1)[0]; itemsA.splice(toIndex, 0, moved); itemsA = [...itemsA]; }, onRemove(item: DndItemData) { const i = itemsA.findIndex((x) => String(x.id) === String(item.id)); if (i < 0) return; const [removed] = itemsA.splice(i, 1); itemsA = [...itemsA]; pendingCross = { item: removed, fromListId: "cross-a" }; }, onReceive(item, fromListId, toIndex) { const data = pendingCross?.fromListId === fromListId ? pendingCross.item : (item as ListItem); itemsA.splice(toIndex, 0, data); itemsA = [...itemsA]; pendingCross = null; }, }), );
const listBAttach = $derived( dndList({ id: "cross-b", axis: "y", acceptFrom: ["cross-a"], showZoneIndicator: false, onReorder(fromIndex, toIndex) { const moved = itemsB.splice(fromIndex, 1)[0]; itemsB.splice(toIndex, 0, moved); itemsB = [...itemsB]; }, onRemove(item: DndItemData) { const i = itemsB.findIndex((x) => String(x.id) === String(item.id)); if (i < 0) return; const [removed] = itemsB.splice(i, 1); itemsB = [...itemsB]; pendingCross = { item: removed, fromListId: "cross-b" }; }, onReceive(item, fromListId, toIndex) { const data = pendingCross?.fromListId === fromListId ? pendingCross.item : (item as ListItem); itemsB.splice(toIndex, 0, data); itemsB = [...itemsB]; pendingCross = null; }, }), );</script>
<div class="grid grid-cols-2 gap-4"> <div class="space-y-1"> <p class="text-[10px] font-medium text-txt-secondary">List A</p> <div {@attach listAAttach} class="min-h-[120px] space-y-1 rounded border border-border-muted p-2" > {#each itemsA as item (item.id)} <div {@attach dndItem({ id: item.id, data: item })} class="cursor-grab rounded bg-surface-raised px-2 py-1.5 text-xs text-txt-primary" > {item.label} </div> {/each} </div> </div> <div class="space-y-1"> <p class="text-[10px] font-medium text-txt-secondary">List B</p> <div {@attach listBAttach} class="min-h-[120px] space-y-1 rounded border border-border-muted p-2" > {#each itemsB as item (item.id)} <div {@attach dndItem({ id: item.id, data: item })} class="cursor-grab rounded bg-surface-raised px-2 py-1.5 text-xs text-txt-primary" > {item.label} </div> {/each} </div> </div></div>OS file drops
Use DropZone from phoundry-ui for file pick / drag-in uploads -
it is separate from list reordering DnD.
DndListOptions
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
idrequired | string | — | Unique list id (also data-dnd-list). |
axis | "x" | "y" | undefined | — | Primary axis for insertion hints (horizontal tabs vs vertical lists). |
acceptFrom | string[] | undefined | — | Source list ids allowed to drop here. Omit for unrestricted cross-list drops. |
sourceOnly | boolean | undefined | — | If true, items can be dragged out but this list does not accept reorder/drops. |
showZoneIndicator | boolean | undefined | — | Dashed outline on list hover during drag; set false for compact chrome (tabs, sidebars). |
onReorder | ((fromIndex: number, toIndex: number) => void) | undefined | — | Same-list reorder after drop. |
onReceive | ((item: DndItemData, fromListId: string, toIndex: number) => void) | undefined | — | Cross-list: item landed in this list (pair with source onRemove). |
onRemove | ((item: DndItemData) => void) | undefined | — | Cross-list: item left this list toward another registered list. |
DndItemOptions
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
idrequired | string | number | — | Stable item id (data-dnd-item). |
data | DndItemData | undefined | — | Payload passed to receivers (defaults to { id }). |
disabled | boolean | undefined | — | If true, item does not start a drag. |
dragHandle | string | undefined | — | CSS selector for the drag handle within the item. Omit to drag from the whole item. |
dragThreshold | number | undefined | — | Pointer movement (px) before a drag starts. |
onClickWithoutDrag | (() => void) | undefined | — | Called on pointer up when movement stayed below dragThreshold (also when disabled). |
onDragStart | (() => void) | undefined | — | Called once when dragThreshold is crossed and a drag begins. |
Usage notes
- Mount
DndGhostandDndIndicatoronce per layout surface that uses this kit (the docs page mounts them below the examples). - Attach
dndListon the scroll/container that wraps draggable rows; attachdndItemon each row (up to three levels of wrapper depth are considered when resolving drop slots). - Interactive controls inside a row (buttons, inputs, links) block drag initiation unless wrapped outside the hit-tested subtree per
dndItemrules. KanbanBoardcomposes these attachments for multi-column cards.
Touch input does not initiate the shared desktop drag session. Native touch scrolling and contextual holds remain available; onClickWithoutDrag applies only to supported drag-session pointers.
CSS styling
.ph-dnd-ghost is the stable identification hook for Drag-and-drop previews. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
The insertion indicator uses .ph-dnd-indicator. Measured coordinates cross into CSS through private custom properties. Existing drag/drop attachments and callbacks remain available.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.
Drag state uses data-ph-dnd-active="true" on the body and
data-ph-dnd-dragging="true" on the dragged source. Replace custom selectors
that used .dnd-active or .dnd-dragging. Drag transitions use shared motion
tokens and stop under reduced motion. The unused .phi-dnd-poof helper was
removed.