svelte-dnd-action

When using deeply nested zones, you can optimize performance by helping the library identify placeholder (shadow) items. Use the SHADOW_ITEM_MARKER_PROPERTY_NAME property on your items and pass it to a data-is-dnd-shadow-item-hint attribute.

Note: When using this hint, you must include it in the key provided to your {#each} block to ensure the key remains unique when a shadow item is present.

<script>
    import {dndzone, SHADOW_ITEM_MARKER_PROPERTY_NAME} from 'svelte-dnd-action';
    let items = [];
</script>

<section>
    <div use:dndzone={{items}} on:consider={e => items = e.detail.items} on:finalize={e => items = e.detail.items}>
        {#each items as item (item.id)}
            <div data-is-dnd-shadow-item-hint={item[SHADOW_ITEM_MARKER_PROPERTY_NAME]}>
                <h1>{item.title}</h1>
            </div>
        {/each}
    </div>
</section>

If you are using Svelte 4 and need to fix type issues with custom events, add the following to your global.d.ts file:

import { Item, DndEvent } from 'svelte-dnd-action';

declare namespace svelteHTML {
    interface HTMLAttributes<T> {
        "on:consider"?: (event: CustomEvent<DndEvent<Item>> & {target: EventTarget & T}) => void;
        "on:finalize"?: (event: CustomEvent<DndEvent<Item>> & {target: EventTarget & T}) => void;
    }
}

declare type Item = import("svelte-dnd-action").Item;
declare type DndEvent<ItemType = Item> = import("svelte-dnd-action").DndEvent<ItemType>;
declare namespace svelteHTML {
    interface HTMLAttributes<T> {
        "on:consider"?: (event: CustomEvent<DndEvent<ItemType>> & {target: EventTarget & T}) => void;
        "on:finalize"?: (event: CustomEvent<DndEvent<ItemType>> & {target: EventTarget & T}) => void;
    }
}

Install the package as a development dependency using yarn or npm. Requires Svelte 3 (>=3.23.0).

yarn add -D svelte-dnd-action

npm install --save-dev svelte-dnd-action

To provide a high-quality experience for screen reader users, add aria-label attributes to both the container and every draggable item. The library will automatically manage ARIA attributes and instructions based on these labels.

Keyboard Support Features:

• Tab into a container to hear instructions.
• Space/Enter on an item to enter dragging mode.
• Arrow keys to move the item position.
• Tab to another container to move the item there.
• Space/Enter or Escape to exit dragging mode.

<h2 id="list-title">{listName}</h2>
<section 
    aria-label="{listName}" 
    use:dndzone="{{items, flipDurationMs}}" 
    on:consider="{handleDndConsider}" 
    on:finalize="{handleDndFinalize}"
>
    {#each items as item(item.id)}
    <div aria-label="{item.name}" animate:flip="{{duration: flipDurationMs}}">
        {item.name}
    </div>
    {/each}
</section>

If your data uses a key other than id (e.g., _id for PouchDB), you can globally override the identifier key. This must be called before any dndzone is rendered, ideally in your top-level App component.

import {overrideItemIdKeyNameBeforeInitialisingDndZones} from "svelte-dnd-action";
overrideItemIdKeyNameBeforeInitialisingDndZones("_id");

The dndzone action dispatches two custom events:

1. consider: Dispatched when a dragged element moves to a new position or leaves a zone. Use this to update the UI immediately.
2. finalize: Dispatched when the element is dropped. Use this for permanent state updates (e.g., saving to a server).

Both events provide e.detail containing:

• items: The updated items list.
• info: An object for advanced logic containing:
  • trigger: One of DRAG_STARTED, DRAGGED_ENTERED, DRAGGED_ENTERED_ANOTHER, DRAGGED_OVER_INDEX, DRAGGED_LEFT, DRAGGED_LEFT_ALL, DROPPED_INTO_ZONE, DROPPED_INTO_ANOTHER, DROPPED_OUTSIDE_OF_ANY, DRAG_STOPPED.
  • id: The ID of the dragged item.
  • source: Either POINTER or KEYBOARD.

You can control global optional behavior using setFeatureFlag.

Currently available flag:

• USE_COMPUTED_STYLE_INSTEAD_OF_BOUNDING_RECT (defaults to false)

import {setFeatureFlag, FEATURE_FLAG_NAMES} from "svelte-dnd-action";
setFeatureFlag(FEATURE_FLAG_NAMES.USE_COMPUTED_STYLE_INSTEAD_OF_BOUNDING_RECT, true);

To see internal debug messages in the console, use setDebugMode(true).

import {setDebugMode} from "svelte-dnd-action";
setDebugMode(true);