@thisux/sveltednd

A lightweight, flexible drag and drop library for Svelte 5 applications. Built with TypeScript and Svelte's runes system for maximum performance and developer experience.

Features

• Svelte 5 Native — Built on Svelte's $state runes for reactive state management
• Dual-Mode Drag — HTML5 Drag API for desktop + Pointer Events for touch/mobile support
• TypeScript-First — Full type safety with generics support throughout
• Flexible Layouts — Vertical, horizontal, and grid layouts with smart drop indicators
• Drag Handles — Optional handle selectors for precise drag control
• Smart Interaction — Automatically protects interactive elements (inputs, buttons, etc.)
• Drop Indicators — Visual feedback showing exactly where items will drop
• Nested Support — Works with nested containers and complex hierarchies
• Lightweight — Minimal footprint with zero external dependencies

Installation

npm install @thisux/sveltednd
# or
bun add @thisux/sveltednd
# or
yarn add @thisux/sveltednd
# or
pnpm add @thisux/sveltednd

Quick Start

<script lang="ts">
    import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

    let items = $state(['Item 1', 'Item 2', 'Item 3']);

    function handleDrop(state: DragDropState<string>) {
        const { draggedItem, sourceContainer, targetContainer, dropPosition } = state;

        // Simple reordering logic
        const dragIndex = items.indexOf(draggedItem);
        let dropIndex = parseInt(targetContainer ?? '0');
        if (dropPosition === 'after') dropIndex++;

        if (dragIndex !== -1) {
            const [item] = items.splice(dragIndex, 1);
            const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
            items.splice(adjusted, 0, item);
        }
    }
</script>

{#each items as item, index (item)}
    <div
        use:draggable={{ container: index.toString(), dragData: item }}
        use:droppable={{ container: index.toString(), callbacks: { onDrop: handleDrop } }}
    >
        {item}
    </div>
{/each}

Core Concepts

1. Draggable Items (use:draggable)

Make any element draggable with the draggable action:

<div use:draggable={{ container: 'my-list', dragData: item }}>
    {item.name}
</div>

2. Droppable Containers (use:droppable)

Create drop zones with the droppable action:

<div use:droppable={{ container: 'my-list', callbacks: { onDrop: handleDrop } }}>
    <!-- Draggable items go here -->
</div>

3. Global State (dndState)

Access real-time drag state anywhere in your app:

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

{#if dndState.isDragging}
    <p>Dragging {dndState.draggedItem?.name} from {dndState.sourceContainer}</p>
{/if}

API Reference

Draggable Options (DraggableOptions<T>)

Droppable Options (DragDropOptions<T>)

DragDropState Interface

interface DragDropState<T = unknown> {
    isDragging: boolean; // Currently dragging?
    draggedItem: T; // Item being dragged
    sourceContainer: string; // Origin container ID
    targetContainer: string | null; // Current drop target
    targetElement: HTMLElement | null; // Element under cursor
    dropPosition: 'before' | 'after' | null; // Where item will drop
    invalidDrop?: boolean; // Over invalid drop zone?
}

Callbacks

interface DragDropCallbacks<T = unknown> {
    onDragStart?: (state: DragDropState<T>) => void;
    onDragEnd?: (state: DragDropState<T>) => void;
    onDragEnter?: (state: DragDropState<T>) => void;
    onDragLeave?: (state: DragDropState<T>) => void;
    onDragOver?: (state: DragDropState<T>) => void;
    onDrop?: (state: DragDropState<T>) => Promise<void> | void;
}

Examples

Sortable List

<script lang="ts">
    import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

    interface Task {
        id: string;
        title: string;
    }

    let tasks = $state<Task[]>([
        { id: '1', title: 'Design review' },
        { id: '2', title: 'Code review' },
        { id: '3', title: 'Deploy to prod' }
    ]);

    function handleDrop(state: DragDropState<Task>) {
        const { draggedItem, targetContainer, dropPosition } = state;
        const dragIndex = tasks.findIndex((t) => t.id === draggedItem.id);
        let dropIndex = parseInt(targetContainer ?? '0');
        if (dropPosition === 'after') dropIndex++;

        if (dragIndex !== -1) {
            const [task] = tasks.splice(dragIndex, 1);
            const adjusted = dragIndex < dropIndex ? dropIndex - 1 : dropIndex;
            tasks.splice(adjusted, 0, task);
        }
    }
</script>

<div class="task-list">
    {#each tasks as task, index (task.id)}
        <div
            use:draggable={{ container: index.toString(), dragData: task }}
            use:droppable={{ container: index.toString(), callbacks: { onDrop: handleDrop } }}
            class="task-item"
        >
            {task.title}
        </div>
    {/each}
</div>

Multiple Containers (Kanban Board)

<script lang="ts">
    import { draggable, droppable, type DragDropState } from '@thisux/sveltednd';

    interface Card {
        id: string;
        title: string;
        status: 'todo' | 'in-progress' | 'done';
    }

    let cards = $state<Card[]>([
        { id: '1', title: 'Task A', status: 'todo' },
        { id: '2', title: 'Task B', status: 'in-progress' },
        { id: '3', title: 'Task C', status: 'done' }
    ]);

    const columns = ['todo', 'in-progress', 'done'] as const;

    function handleDrop(state: DragDropState<Card>) {
        const { draggedItem, targetContainer } = state;
        if (!targetContainer) return;

        cards = cards.map((c) =>
            c.id === draggedItem.id ? { ...c, status: targetContainer as Card['status'] } : c
        );
    }
</script>

<div class="board">
    {#each columns as column}
        <div use:droppable={{ container: column, callbacks: { onDrop: handleDrop } }} class="column">
            <h3>{column}</h3>
            {#each cards.filter((c) => c.status === column) as card (card.id)}
                <div use:draggable={{ container: column, dragData: card }} class="card">
                    {card.title}
                </div>
            {/each}
        </div>
    {/each}
</div>

Drag Handles

Use the handle option to restrict dragging to a specific element:

<div
    use:draggable={{
        container: 'items',
        dragData: item,
        handle: '.drag-handle' // Only the grip icon starts dragging
    }}
>
    <span class="drag-handle">⋮⋮</span>
    <span>{item.name}</span>
    <!-- Text remains selectable, buttons remain clickable -->
</div>

Custom CSS Classes

Override default styling with custom classes:

<div
    use:draggable={{
        container: 'list',
        dragData: item,
        attributes: { draggingClass: 'my-dragging opacity-50' }
    }}
    use:droppable={{
        container: 'list',
        callbacks: { onDrop: handleDrop },
        attributes: { dragOverClass: 'my-dropzone bg-blue-100' }
    }}
>
    {item}
</div>

Grid Layout

For grid layouts, the library uses nearest-edge detection:

<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 Lists

<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>

Conditional Dropping

Control which items can be dropped where:

<script lang="ts">
    function handleDragOver(state: DragDropState<Item>) {
        // Mark invalid drops
        dndState.invalidDrop = !isValidDrop(state.draggedItem, state.targetContainer);
    }

    function handleDrop(state: DragDropState<Item>) {
        if (dndState.invalidDrop) return;
        // Process the drop
    }
</script>

<div
    use:droppable={{
        container: 'filtered',
        callbacks: {
            onDragOver: handleDragOver,
            onDrop: handleDrop
        }
    }}
>
    <!-- Items -->
</div>

Async Drop Handlers

Drop callbacks support async operations:

<div
    use:droppable={{
        container: 'list',
        callbacks: {
            onDrop: async (state) => {
                await saveToDatabase(state.draggedItem);
                await refreshData();
            }
        }
    }}
>
    <!-- Items -->
</div>

Default CSS Classes

The library provides these default classes (all customizable):

/* Applied while dragging */
.dragging {
    opacity: 0.5;
}

/* Applied when dragged over */
.drag-over {
    outline: 2px dashed #4caf50;
}

/* Drop position indicators */
.drop-before::before,      /* Line above element */
.drop-after::after,        /* Line below element */
.drop-left::before,        /* Line to left (horizontal) */
.drop-right::after {
    /* Line to right (horizontal) */
    content: '';
    position: absolute;
    background-color: #3b82f6;
    pointer-events: none;
}

More Examples

Explore the demo pages for complete working examples:

• Kanban Board — Full-featured board with multiple columns
• Simple Sortable List — Basic reordering
• Grid Sort — 2D grid reordering
• Horizontal Scroll — Horizontal lists
• Nested Containers — Hierarchical drag and drop
• Drag Handles — Handle-based dragging
• Custom Classes — Custom styling
• Interactive Elements — Forms inside draggable items
• Conditional Check — Validation before drop

Using with Components (Svelte 5.29+)

Svelte actions (use:draggable, use:droppable) only work on native HTML elements, not components. If you need to use drag and drop on a component, Svelte 5.29+ provides fromAction to convert actions into attachments that pass through component props:

<script lang="ts">
    import { fromAction } from 'svelte/attachments';
    import { draggable, droppable } from '@thisux/sveltednd';
</script>

<!-- Works on components that spread props onto their root element -->
<Card {@attach fromAction(draggable, { container: 'list', dragData: item })}>
    {item.title}
</Card>

<Column {@attach fromAction(droppable, { container: 'todo', callbacks: { onDrop: handleDrop } })}>
    <!-- draggable items -->
</Column>

The component just needs to spread its props onto a root element:

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

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

Note: Requires Svelte 5.29 or newer. On older versions, wrap the component in a <div> with the action instead.

Browser Support

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+
• Mobile Safari (iOS 14+)
• Chrome for Android

Requirements

• Svelte 5.0 or higher
• TypeScript 5.0 or higher (optional but recommended)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Acknowledgment

Created by Sanju, founder of ThisUX Private Limited — a design-led product studio. If you need help building your next product, let's talk.