# @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. [![npm version](https://badge.fury.io/js/@thisux%2Fsveltednd.svg)](https://www.npmjs.com/package/@thisux/sveltednd) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Copyright](https://img.shields.io/badge/©-THISUX%20Private%20Limited-111111.svg)](LICENSE) [![skills.sh](https://skills.sh/b/thisuxhq/sveltednd)](https://skills.sh/thisuxhq/sveltednd) **Docs & community:** [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) · [Code of Conduct](CODE_OF_CONDUCT.md) ## 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 (`containerGroup` keeps indicators on matching levels) - **Attachments** — First-class `{@attach}` factories for components (Svelte 5.29+) - **Keyboard** — Opt-in Space/arrows/Escape reordering with screen-reader announcements - **Lightweight** — Minimal footprint with zero external dependencies ## Installation ```bash npm install @thisux/sveltednd # or bun add @thisux/sveltednd # or yarn add @thisux/sveltednd # or pnpm add @thisux/sveltednd ``` ## Agent skill Coding agents can install the SvelteDnD skill for API patterns, reorder recipes, attachments, and keyboard guidance: ```bash npx skills add thisuxhq/sveltednd # or a single skill npx skills add thisuxhq/sveltednd --skill sveltednd ``` Skill source: [`skills/sveltednd/`](skills/sveltednd/). Directory: [skills.sh/thisuxhq/sveltednd](https://skills.sh/thisuxhq/sveltednd). ## Quick Start ```svelte {#each items as item, index (item)}
{item}
{/each} ``` ## Core Concepts ### 1. Draggable Items (`use:draggable`) Make any element draggable with the `draggable` action: ```svelte
{item.name}
``` ### 2. Droppable Containers (`use:droppable`) Create drop zones with the `droppable` action: ```svelte
``` ### 3. Global State (`dndState`) Access real-time drag state anywhere in your app: ```svelte {#if dndState.isDragging}

Dragging {dndState.draggedItem?.name} from {dndState.sourceContainer}

{/if} ``` ## API Reference ### Draggable Options (`DraggableOptions`) | Property | Type | Description | | ------------- | ---------- | ------------------------------------------------------------------------- | | `container` | `string` | **Required.** Container identifier for grouping items | | `dragData` | `T` | **Required.** Data payload to transfer during drag | | `disabled` | `boolean` | Disable dragging for this element | | `handle` | `string` | CSS selector for drag handle (e.g., `'.drag-handle'`) | | `interactive` | `string[]` | Additional selectors for interactive elements that shouldn't trigger drag | | `callbacks` | `object` | Event callbacks (`onDragStart`, `onDragEnd`) | | `attributes` | `object` | CSS class overrides (`draggingClass`) | ### Droppable Options (`DragDropOptions`) | Property | Type | Description | | ------------ | -------------------------------------- | ---------------------------------------------------------------------- | | `container` | `string` | **Required.** Container identifier | | `disabled` | `boolean` | Disable dropping for this element | | `direction` | `'vertical' \| 'horizontal' \| 'grid'` | Layout direction (default: `'vertical'`) | | `callbacks` | `object` | Event callbacks (`onDragEnter`, `onDragLeave`, `onDragOver`, `onDrop`) | | `attributes` | `object` | CSS class overrides (`dragOverClass`) | ### DragDropState Interface ```typescript interface DragDropState { 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 ```typescript interface DragDropCallbacks { onDragStart?: (state: DragDropState) => void; onDragEnd?: (state: DragDropState) => void; onDragEnter?: (state: DragDropState) => void; onDragLeave?: (state: DragDropState) => void; onDragOver?: (state: DragDropState) => void; onDrop?: (state: DragDropState) => Promise | void; } ``` ## Examples ### Sortable List ```svelte
{#each tasks as task, index (task.id)}
{task.title}
{/each}
``` ### Multiple Containers (Kanban Board) ```svelte
{#each columns as column}

{column}

{#each cards.filter((c) => c.status === column) as card (card.id)}
{card.title}
{/each}
{/each}
``` ### Drag Handles Use the `handle` option to restrict dragging to a specific element: ```svelte
⋮⋮ {item.name}
``` ### Custom CSS Classes Override default styling with custom classes: ```svelte
{item}
``` ### Grid Layout For grid layouts, the library uses nearest-edge detection: ```svelte
{#each items as item, index (item.id)}
{item.name}
{/each}
``` ### Horizontal Lists ```svelte
{#each items as item, index (item.id)}
{item}
{/each}
``` ### Conditional Dropping Control which items can be dropped where: ```svelte
``` ### Async Drop Handlers Drop callbacks support async operations: ```svelte
{ await saveToDatabase(state.draggedItem); await refreshData(); } } }} >
``` ## Default CSS Classes The library provides these default classes (all customizable): ```css /* 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](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/+page.svelte)** — Full-featured board with multiple columns - **[Simple Sortable List](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/simple-list/+page.svelte)** — Basic reordering - **[Grid Sort](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/grid-sort/+page.svelte)** — 2D grid reordering - **[Horizontal Scroll](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/horizontal-scroll/+page.svelte)** — Horizontal lists - **[Nested Containers](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/nested/+page.svelte)** — Hierarchical drag and drop - **[Drag Handles](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/drag-handle/+page.svelte)** — Handle-based dragging - **[Custom Classes](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/custom-classes/+page.svelte)** — Custom styling - **[Interactive Elements](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/interactive-elements/+page.svelte)** — Forms inside draggable items - **[Conditional Check](https://github.com/thisuxhq/SvelteDnD/blob/main/src/routes/conditional-check/+page.svelte)** — Validation before drop - **[Attachments](https://github.com/thisuxhq/sveltednd/blob/main/src/routes/attach/+page.svelte)** — `{@attach}` on components - **[Keyboard](https://github.com/thisuxhq/sveltednd/blob/main/src/routes/keyboard/+page.svelte)** — Space / arrows / Escape reordering ## Keyboard accessibility (opt-in) Enable keyboard reordering with `keyboard: true` on a **draggable**. Mouse and touch behavior are unchanged when the option is omitted. | Key | Action | | ----------------------------------- | ------------------------------------------------- | | **Tab** | Focus a keyboard-enabled item | | **Space** / **Enter** | Pick up, or drop while dragging | | **↑ / ↓** (or ← / → for horizontal) | Move the drop preview among registered drop zones | | **Escape** | Cancel without calling `onDrop` | ```svelte {#each items as item, index (item)}
{item}
{/each} ``` Notes: - Keyboard uses the **same** `onDrop` contract as pointer/HTML5 — your data model stays in the app. - An assertive live region announces grab / move / drop / cancel for screen readers. - Interactive children (inputs, buttons, …) still receive Space/Enter normally. - Cross-column Kanban keyboard navigation is planned as a follow-up (`navigation: 'containers'`). Live demo: [Keyboard](https://sveltednd.thisux.com/keyboard) · [source](https://github.com/thisuxhq/sveltednd/blob/main/src/routes/keyboard/+page.svelte) ## Using with Components — `{@attach}` (Svelte 5.29+) Svelte actions (`use:draggable`, `use:droppable`) only work on **native HTML elements**. For **components**, use the first-class attachment factories: | API | Use on | Syntax | | ------------------------------------- | -------------------------- | -------------------------------- | | `draggable` / `droppable` | HTML elements | `use:draggable={...}` | | `attachDraggable` / `attachDroppable` | Elements **or** components | `{@attach attachDraggable(...)}` | Pass a **getter** (`() => options`) when options depend on reactive state — that keeps generics intact and updates the underlying action without remounting. ```svelte ({ container: 'list', dragData: task }))} > {task.title} (() => ({ container: 'todo', callbacks: { onDrop: handleDrop } }))} > ``` Your component must forward props (and thus attachments) to a real DOM node: ```svelte
{@render children?.()}
``` You can still use `fromAction` from `svelte/attachments` with the raw actions if you prefer, but always pass a **function** as the second argument: ```svelte
({ container: 'list', dragData: item }))}>
``` > **Note:** Attachments require **Svelte 5.29+** (`fromAction` is available in current 5.x). > On older versions, wrap the component in a `
` and use `use:draggable` / `use:droppable`. Live demo: [Attachments](https://sveltednd.thisux.com/attach) · [source](https://github.com/thisuxhq/sveltednd/blob/main/src/routes/attach/+page.svelte) ## 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](CONTRIBUTING.md) for setup, coding style, Conventional Commits, and PR guidelines. Please also follow the [Code of Conduct](CODE_OF_CONDUCT.md). Security vulnerabilities should be reported privately — see [SECURITY.md](SECURITY.md). ## Changelog See [CHANGELOG.md](CHANGELOG.md) for release history. ## License Copyright © 2024–2026 [THISUX Private Limited](https://github.com/thisuxhq). Released under the [MIT License](LICENSE). You may use, modify, and distribute this project for personal and commercial purposes, provided the copyright and permission notice are retained. ## Acknowledgment Created by [Sanju](https://sanju.sh), founder of [THISUX Private Limited](https://thisux.com) — a design-led product studio. If you need help building your next product, [let's talk](https://cal.com/imsanju/15min).