@thisux/sveltednd Documentation

Choose between standard Svelte actions or the {@attach} factory based on your component structure:

• use:draggable / use:droppable: Use these for plain HTML elements within your current component.
• attachDraggable / attachDroppable: Use these for custom Svelte components (requires Svelte 5.29+). The component must spread its props onto a root element (e.g., <div {...props}>).

Best Practice: When using attachments, pass a getter function to the attachment so that the options (like container or dragData) remain reactive when your data changes.

<Card
	{@attach attachDraggable(() => ({
		container: columnId,
		dragData: task
	}))}
>
	{task.title}
</Card>

<Column
	{@attach attachDroppable(() => ({
		container: columnId,
		callbacks: { onDrop: handleDrop }
	}))}
>
	<!-- cards -->
</Column>

When implementing nested zones (a droppable inside another droppable), the deepest matching droppable handles the drop.

Best Practices:

• Ensure both parent and child zones have distinct container IDs.
• Validate the targetContainer inside your onDrop callback to ensure the item is being moved to the intended level.

The library follows a data-agnostic approach where you own the state. It provides the interaction layer, but does not mutate your data arrays.

Core Concepts

• container: A string ID representing a list, column, or zone. The library compares sourceContainer and targetContainer to determine if a move is valid.
• dragData: A typed payload (T) carried through the drag operation. It is recommended to use stable objects containing a unique id.
• dndState: A global reactive snapshot providing real-time information such as isDragging, draggedItem, active containers, dropPosition, and invalidDrop status.
• Data Ownership: You must implement the actual data reordering or movement logic inside the onDrop callback using the information provided in the DragDropState.

Keyboard drops trigger the exact same onDrop callback as mouse or touch interactions. The resulting DragDropState object will have dndState.dragInput === 'keyboard' during the session.

If you use conditional validation by setting dndState.invalidDrop in your onDragOver callback, the library will automatically announce the invalidity to screen readers and prevent the keyboard drop from committing.

Control the drop direction using the direction property in use:droppable.

• Grid: Uses nearest-edge detection for grid layouts.
• Horizontal: Optimized for horizontal lists.

<!-- Grid Layout -->
<div class="grid grid-cols-3 gap-4">
	{#each items as item, index (item.id)}
		<div
			use:draggable={{ container: index.toString(), dragData: item }}
			use:droppable={{
				container: index.toString(),
				direction: 'grid',
				callbacks: { onDrop: handleDrop }
			}}
		>
			{item.name}
		</div>
	{/each}
</div>

<!-- Horizontal Layout -->
<div class="flex gap-4">
	{#each items as item, index (item.id)}
		<div
			use:draggable={{ container: index.toString(), dragData: item }}
			use:droppable={{
				container: index.toString(),
				direction: 'horizontal',
				callbacks: { onDrop: handleDrop }
			}}
		>
			{item}
		</div>
	{/each}
</div>

The dndState object provides global information about the current drag operation, which can be used to build overlays, ghost UIs, or accessibility announcements.

Commonly used properties:

• dndState.isDragging: Boolean indicating if a drag operation is active.
• dndState.sourceContainer: The ID of the container where the drag started.
• dndState.invalidDrop: Boolean indicating if the current hover target is invalid.

Example Usage:

<script>
	import { dndState } from '@thisux/sveltednd';
</script>

{#if dndState.isDragging}
	<p class="sr-only">Dragging from {dndState.sourceContainer}</p>
{/if}

#!svelte
<script>
	import { dndState } from '@thisux/sveltednd';
</script>

{#if dndState.isDragging}
	<p class="sr-only">Dragging from {dndState.sourceContainer}</p>
{/if}

You can enable keyboard-based reordering by setting keyboard: true in the draggable action options. This allows users to interact with the drag-and-drop interface using a keyboard instead of a mouse or touch.

Keyboard Controls:

• Tab: Focus a keyboard-enabled item.
• Space / Enter: Pick up an item, or drop it while dragging.
• ↑ / ↓ (or ← / → for horizontal lists): Move the drop preview among registered drop zones.
• Escape: Cancel the operation without triggering the onDrop callback.

Keyboard reordering uses the same onDrop contract as pointer/HTML5 interactions, ensuring your data model logic remains consistent.

<div
	use:draggable={{
		container: 'container-id',
		dragData: item,
		keyboard: true
	}}
>...</div>

To ensure attachDraggable and attachDroppable work correctly on custom components, the component must spread its props onto a root DOM element. This allows the attachment logic to bind to the actual element in the DOM.

Example Component Pattern:

<script lang="ts">
	let { children, ...props } = $props();
</script>

<div {...props}>
	{@render children?.()}
</div>

<!-- Card.svelte -->
<script lang="ts">
	let { children, ...props } = $props();
</script>

<div {...props}>
	{@render children?.()}
</div>