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

Docs & community: Contributing · Security · Changelog · Code of Conduct

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

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:

npx skills add thisuxhq/sveltednd
# or a single skill
npx skills add thisuxhq/sveltednd --skill sveltednd

Skill source: skills/sveltednd/. Directory: skills.sh/thisuxhq/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>`)

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<T>`)

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

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
Attachments — {@attach} on components
Keyboard — 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`

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

	let items = $state(['Alpha', 'Beta', 'Gamma']);

	function handleDrop(state: DragDropState<string>) {
		const from = items.indexOf(state.draggedItem);
		let to = parseInt(state.targetContainer ?? '0');
		if (state.dropPosition === 'after') to += 1;
		if (from === -1) return;
		const next = [...items];
		const [item] = next.splice(from, 1);
		next.splice(from < to ? to - 1 : to, 0, item);
		items = next;
	}
</script>

{#each items as item, index (item)}
	<div
		use:draggable={{
			container: index.toString(),
			dragData: item,
			keyboard: true
		}}
		use:droppable={{
			container: index.toString(),
			callbacks: { onDrop: handleDrop }
		}}
	>
		{item}
	</div>
{/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 · source

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.

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

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

	let task = $state<Task>({ id: '1', title: 'Ship attach API' });

	function handleDrop(state: DragDropState<Task>) {
		// update your data
	}
</script>

<!-- Component roots: works because Card/Column spread {...props} onto an element -->
<Card
	{@attach attachDraggable(() => ({
		container: 'list',
		dragData: task
	}))}
>
	{task.title}
</Card>

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

Your component must forward props (and thus attachments) to a real DOM node:

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

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

You can still use fromAction from svelte/attachments with the raw actions if you prefer, but always pass a function as the second argument:

<!-- Correct -->
<div {@attach fromAction(draggable, () => ({ container: 'list', dragData: item }))}></div>

<!-- Incorrect — second arg must be a getter, not the options object -->
<div {@attach fromAction(draggable, { container: 'list', dragData: item })}></div>

Note: Attachments require Svelte 5.29+ (fromAction is available in current 5.x). On older versions, wrap the component in a <div> and use use:draggable / use:droppable.

Live demo: Attachments · source

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 setup, coding style, Conventional Commits, and PR guidelines. Please also follow the Code of Conduct.

Security vulnerabilities should be reported privately — see SECURITY.md.

Changelog

See CHANGELOG.md for release history.

License

Released under the MIT 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, founder of THISUX Private Limited — a design-led product studio. If you need help building your next product, let's talk.

Name		Name	Last commit message	Last commit date
Latest commit History 179 Commits
.github		.github
.husky		.husky
skills/sveltednd		skills/sveltednd
src		src
static		static
.gitignore		.gitignore
.node-version		.node-version
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
commitlint.config.js		commitlint.config.js
context7.json		context7.json
eslint.config.js		eslint.config.js
package.json		package.json
postcss.config.js		postcss.config.js
release-please-config.json		release-please-config.json
skills.sh.json		skills.sh.json
svelte.config.js		svelte.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
wrangler.toml		wrangler.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@thisux/sveltednd

Features

Installation

Agent skill

Quick Start

Core Concepts

1. Draggable Items (use:draggable)

2. Droppable Containers (use:droppable)

3. Global State (dndState)

API Reference

Draggable Options (DraggableOptions<T>)

Droppable Options (DragDropOptions<T>)

DragDropState Interface

Callbacks

Examples

Sortable List

Multiple Containers (Kanban Board)

Drag Handles

Custom CSS Classes

Grid Layout

Horizontal Lists

Conditional Dropping

Async Drop Handlers

Default CSS Classes

More Examples

Keyboard accessibility (opt-in)

Using with Components — {@attach} (Svelte 5.29+)

Browser Support

Requirements

Contributing

Changelog

License

Acknowledgment

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

1. Draggable Items (`use:draggable`)

2. Droppable Containers (`use:droppable`)

3. Global State (`dndState`)

Draggable Options (`DraggableOptions<T>`)

Droppable Options (`DragDropOptions<T>`)

Using with Components — `{@attach}` (Svelte 5.29+)