Skip to content

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
sortable-list.svelte
<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
cross-list-transfer.svelte
<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

NameTypeDefaultDescription
idrequiredstring—Unique list id (also data-dnd-list).
axis"x" | "y" | undefined—Primary axis for insertion hints (horizontal tabs vs vertical lists).
acceptFromstring[] | undefined—Source list ids allowed to drop here. Omit for unrestricted cross-list drops.
sourceOnlyboolean | undefined—If true, items can be dragged out but this list does not accept reorder/drops.
showZoneIndicatorboolean | 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

NameTypeDefaultDescription
idrequiredstring | number—Stable item id (data-dnd-item).
dataDndItemData | undefined—Payload passed to receivers (defaults to { id }).
disabledboolean | undefined—If true, item does not start a drag.
dragHandlestring | undefined—CSS selector for the drag handle within the item. Omit to drag from the whole item.
dragThresholdnumber | 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 DndGhost and DndIndicator once per layout surface that uses this kit (the docs page mounts them below the examples).
  • Attach dndList on the scroll/container that wraps draggable rows; attach dndItem on 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 dndItem rules.
  • KanbanBoard composes 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.