# svelte-dnd > Drag and drop for Svelte 5: nested zones, touch, keyboard and screen reader support. # Getting started `@lukez/svelte-dnd` is a drag and drop library for Svelte 5. You write a list with an `#each` block, put one attachment on its container, and the user can sort it with the pointer, a touch screen or the keyboard. ## Install ```bash pnpm add @lukez/svelte-dnd ``` ```bash npm install @lukez/svelte-dnd ``` ```bash yarn add @lukez/svelte-dnd ``` The peer range is `svelte ^5.32.0`, because the library uses attachments. It has no other dependencies. ## A first list ```svelte
({ items, flipDurationMs, onconsider: update, onfinalize: update }))}> {#each items as item (item.id)}
{item.name}
{/each}
``` Four things make this work: - `dndzone` is an attachment. It turns the `
` into a zone and each of its direct children into a draggable item. It takes a function that returns the options, so it reads your current `items` each time they change. - Every item has an `id`, and the `#each` block uses it as its key. Keyed blocks are required. - `onconsider` and `onfinalize` get the event directly. `e.items` is the list the zone should render, and `e.info` says what happened. - `flipDurationMs` is given to the options and to `animate:flip`, so the library and the animation agree on how long a move takes. See [Options](/docs/api/options) for every option the getter can return. ## Why you write `items` back twice The library never changes your list. It tells you what the list should look like, and you assign it: - `onconsider` runs again and again while the user drags: the item has entered the zone, moved over another index, or left. The `items` it gives you include a temporary placeholder, so the other items make room. Render that list to show the user where the item would land. - `onfinalize` runs when the item is dropped, in the zone the item was dropped into and in the zone it came from. The `items` it gives you are the final list. A pointer drag sends it once, at the end. A keyboard drag sends it on every arrow key and ends with an `onconsider`, so read [saving after a drag](/docs/guides/keyboard-and-screen-readers#saving-after-a-drag) before you save to a server from it. Both handlers usually do the same thing, `items = e.items`, so the sample above shares one function. They are two options because they mean different things: a drag in progress and a result. The library relies on both to keep your list in step with the drag, so do not leave either one out. [How it works](/docs/how-it-works) explains the full lifecycle. ## Next steps - [How it works](/docs/how-it-works): the consider and finalize lifecycle, the placeholder item, zone types and item ids. - [Options](/docs/api/options): every option of a zone. - The guides: [drag handles](/docs/guides/drag-handles), [nested zones](/docs/guides/nested-zones), [keyboard and screen readers](/docs/guides/keyboard-and-screen-readers), [styling](/docs/guides/styling) and more. # How it works ## You own the items A zone does not hold state. You give it `items`, the list you render in your `#each` block, and the library reads the DOM and the pointer to work out what the list should become. It does not assign to your list. It calls `onconsider` and `onfinalize` with the proposed list, and you decide what to do with it. In most apps that is `items = e.items`. Because of that, the library works with any state you have: a `$state` array, a prop, a store, or a list you copy and send to a server before you accept it. ## Consider and finalize Every event has the same shape: `e.items` is the list the zone should render, and `e.info` describes what happened. - `onconsider` is for a drag in progress. It fires as the dragged item enters a zone, moves over another index, or leaves. Render the list you receive so the other items make room. - `onfinalize` is for a result. It fires when the item is dropped, in the zone the item was dropped into and in the zone it came from, if that is another one. A pointer drag sends it once, when the drag ends. A keyboard drag drops the item on every arrow key, so it sends `onfinalize` on every move, and ends with an `onconsider` with the `DRAG_STOPPED` trigger. To save to a server once per drag, see [saving after a drag](/docs/guides/keyboard-and-screen-readers#saving-after-a-drag). `e.info` has three fields: `trigger`, the kind of event, `id`, the id of the dragged item, and `source`, which is `"pointer"` or `"keyboard"`. Most apps ignore it. Copy on drag and similar behaviors use it. The triggers are the values of the exported `TRIGGERS` object. Triggers marked pointer only never happen in a keyboard drag. | Event | Trigger (`TRIGGERS.…`) | Sent to, and when | | ------------ | ------------------------- | --------------------------------------------------------------------------------------------- | | `onconsider` | `DRAG_STARTED` | The zone the drag started from. | | `onconsider` | `DRAGGED_ENTERED` | A zone the item entered. Pointer only. | | `onconsider` | `DRAGGED_ENTERED_ANOTHER` | The zone the drag started from, when the item enters another zone. Pointer only. | | `onconsider` | `DRAGGED_OVER_INDEX` | A zone, when the item moves over another index of it. Pointer only. | | `onconsider` | `DRAGGED_LEFT` | A zone the item left. Pointer only. | | `onconsider` | `DRAGGED_LEFT_ALL` | The zone the drag started from, when the item is outside of every zone. Pointer only. | | `onconsider` | `DRAG_STOPPED` | The zone, when the user ends a keyboard drag. Keyboard only. | | `onfinalize` | `DROPPED_INTO_ZONE` | The zone the item was dropped into. A keyboard drag sends it each time an arrow key moves it. | | `onfinalize` | `DROPPED_INTO_ANOTHER` | The zone the item came from, when it is dropped into another zone. | | `onfinalize` | `DROPPED_OUTSIDE_OF_ANY` | The zone the item came from, when it is dropped outside of every zone. Pointer only. | A drag within one zone sends `onfinalize` to that zone only. A drag from one zone to another sends it to both, so both lists must be updated. That is another reason to keep the handlers simple: assign what you get. ## The shadow item During a pointer drag, the zone the item hovers over receives a temporary item in its `items`: the shadow item. It is a copy of the dragged item's data with two changes: - its id starts as `SHADOW_PLACEHOLDER_ITEM_ID`. Once the dragged element has left the list, the shadow item takes the dragged item's own id, so the id is not a reliable way to find it. - it has the property `isDndShadowItem` set to `true`. The name is exported as `SHADOW_ITEM_MARKER_PROPERTY_NAME`. Check this marker to recognise the shadow item. It is what makes the other items move aside, and it marks where the item would land. While it is in the list, the element it renders is the placeholder under the dragged element, which follows the pointer. When the drag ends, the shadow item is replaced by the dragged item with its real id. Check the marker in your `#each` block to style the placeholder: ```svelte ``` Two more things to know about it: - Your rendering code sees it, so a nested zone that filters or counts items must expect it. Filter on the `isDndShadowItem` marker when you pass `items` down to a nested zone. - With nested zones, mark the item with `data-is-dnd-shadow-item-hint={item.isDndShadowItem}` so the library does not set up zones inside the placeholder. See [nested zones](/docs/guides/nested-zones#the-shadow-hint). Keyboard drags do not add a shadow item. The item moves in the list directly. ## Zone types By default every zone has the same type, so an item can move between any two zones. Give zones a `type` to limit that: an item can only be dropped in a zone of its own type. ```svelte