Migrating from svelte-dnd-action
Move from svelte-dnd-action to @lukez/svelte-dnd: attachments instead of actions, callbacks instead of events, and configure instead of the global setters.
@lukez/svelte-dnd is a rewrite of the public API for Svelte 5. The drag and drop behavior (pointer, touch, keyboard, aria, scrolling, nested zones, drag handles, other windows) is the same, with one fix for nested zones with the shadow item hint (see Nested zones and the shadow item hint). What changed is how you attach a zone, how you receive updates, and how you configure the library.
Overview
svelte-dnd-action | @lukez/svelte-dnd |
|---|---|
npm i svelte-dnd-action | npm i @lukez/svelte-dnd |
| Svelte 3, 4 or 5 | Svelte ^5.32.0 |
use:dndzone={options} | {@attach dndzone(() => ({ ...options }))} |
on:consider, on:finalize, e.detail | onconsider, onfinalize options, e |
setAriaStrings, setKeyboardDragTrigger, setDebugMode, overrideItemIdKeyNameBefore... | configure({ ariaStrings, keyboardDragTrigger, debug, idKey }) |
setFeatureFlag(FEATURE_FLAG_NAMES.USE_COMPUTED_STYLE_INSTEAD_OF_BOUNDING_RECT, true) | useComputedStyleForRects: true zone option |
use:dragHandleZone, use:dragHandle | {@attach dragHandleZone(() => ({ ...options }))}, {@attach dragHandle} |
Package name
Install the new package, remove the old one, and change the import path.
Before:
After:
Svelte version
Attachments need Svelte 5.29, and the fromAction helper that dndzone is built on needs ^5.32.0. The package declares svelte ^5.32.0 as a peer dependency. Svelte 3 and 4 are not supported.
The action became an attachment
dndzone is no longer an action. It returns an attachment, and you pass it with {@attach}. The options go in a function that returns them (a getter), not in a plain object. The library reads the getter inside an effect, so the zone is created once and picks up new options (and a new items array) without being torn down in the middle of a drag.
Before:
After:
The getter is required. Passing a plain object is a type error.
Reassign items, do not change it in place. The library notices a change because the getter reads the items binding, so items = next works and items.push(x) on its own does not. This is the same rule as in svelte-dnd-action, and the callbacks below hand you a new array to assign.
You can keep all the options in one $state object and return it, as () => options or () => ({ ...options }). The library copies the top level of what the getter returns inside the effect, so it reads each option and sees a write such as options.items = e.items or options.dragDisabled = true. A change deeper down, such as options.items.push(x), is not seen, the same as for items above.
Events became callbacks
The consider and finalize DOM events are gone. Pass onconsider and onfinalize in the options instead. The callback receives what e.detail used to hold, so e.detail.items becomes e.items and e.detail.info becomes e.info.
Before:
After:
The callbacks fire at the same points as the old events. The library no longer dispatches consider or finalize on the element, so an onconsider={...} attribute on the element does nothing. Put the callbacks in the options.
When you let TypeScript infer the types, the item type flows from items into the callbacks, and you can write onconsider: (e) => (items = e.items).
info.id is not typed as a string
info.id is the raw value of the item’s id key, not a string. Its type is inferred from the item’s id field, so { id: number } items give a number. An optional id field ({ id?: number }) also gives number, without undefined, because the id is required at runtime. An item type with no id field gives unknown: that is the case with a custom idKey, and for the default Item type. Narrow an unknown id before string-only use.
Global setters became configure
The four global setters are replaced by one function, configure. Keys that you leave out are not touched, so configure({ ariaStrings }) on a locale change leaves the keyboard trigger as it was.
| Before | After |
|---|---|
overrideItemIdKeyNameBeforeInitialisingDndZones(k) | configure({ idKey: k }) |
setKeyboardDragTrigger(t) | configure({ keyboardDragTrigger: t }) |
setAriaStrings(s) | configure({ ariaStrings: s }) |
setDebugMode(b) | configure({ debug: b }) |
Before:
After:
Behavior to know about:
keyboardDragTriggeris"space","enter"or"space_or_enter"(the default).nullrestores the default.ariaStringsis a full locale over the English defaults.nullrestores English.idKeythrows while any zone is mounted, as before. Call it once at app start. A value that is not a string throws too.- An unknown key throws, so a typo fails loudly.
configureonly sets module state and touches no DOM, so it is safe to call during SSR.
The feature flag became a zone option
setFeatureFlag and FEATURE_FLAG_NAMES are removed. The only flag, USE_COMPUTED_STYLE_INSTEAD_OF_BOUNDING_RECT, is now the useComputedStyleForRects option of the zone. It is a workaround for grid layouts, so set it on the zone that has the grid. Other zones keep the default (false).
Before:
After:
Drag handles are attachments
dragHandleZone and dragHandle are attachments too (see the drag handles guide). Put {@attach dragHandleZone(() => options)} on the zone and {@attach dragHandle} on each handle element. dragHandle is used as it is, without a function call.
Before:
After:
A handle finds the nearest handle zone around it. A handle outside any handle zone does nothing. When debug is on, each such handle logs one debug message when it is removed.
dragDisabled is per handle zone
Before, the dragDisabled option of one handle zone leaked into the handles of every other handle zone on the page. Now it applies to the handles of its own zone only. A zone with dragDisabled: true stops its own handles and leaves the others alone.
Nested handle zones follow the same rule: the handles inside an inner zone answer to the inner zone’s dragDisabled, and the outer zone’s dragDisabled does not reach them.
Dragging an item from one handle zone into another still works. While a drag is running, every handle zone accepts it, and all of them are disabled again when it ends.
Here the handles of the left list are locked, and the handles of the right list still work.
Nested zones and the shadow item hint
A zone nested inside an item of another zone works as before (see the nested zones guide). While an item is dragged, its zone shows a shadow item in its place, and Svelte renders the nested zone inside the shadow item too. To keep that copy from registering as a second zone for the length of the drag, mark the shadow item’s element with data-is-dnd-shadow-item-hint, as in svelte-dnd-action:
Under strict TypeScript, the item type needs the optional field [SHADOW_ITEM_MARKER_PROPERTY_NAME]?: boolean (that is, isDndShadowItem?: boolean), because the engine sets it on the shadow item.
Fixed in this release: in svelte-dnd-action, with the hint, the nested zone of the dragged item stayed dead after the drop. The library skipped a zone created inside a marked element and never set it up later, and after the drop the shadow item’s element stays on as the dropped item’s element. Now the skipped zone is set up as soon as the hint is removed, so the dropped item’s nested zone takes drags again (#7).
Type changes
- The public generics take
T extends object, so aninterfaceworks as an item type. Before, only types with an index signature did. transformDraggedElementreceives the zone’s item type:TransformDraggedElementFunction<T>is(element?, draggedElementData?: T, index?) => void.DndZoneAttributesis removed. There are no event attributes left to type.DndEventInfotakes the item type,DndEventInfo<T>, andidis inferred from the item’sidfield instead of typedstring, see above.ItemisRecord<string, unknown>instead ofRecord<string, any>. Code that leaves the item type out, such as a handler typed(e: DndEvent) => ..., getsunknownvalues, soe.items[0].nameno longer compiles. Pass your item type, as inDndEvent<Row>, or let TypeScript infer it fromitems.- New types:
DndConfig(the argument ofconfigure). See the types reference and the events reference.
Removed exports
| Removed | Use instead |
|---|---|
setAriaStrings, setKeyboardDragTrigger, setDebugMode, overrideItemIdKeyNameBeforeInitialisingDndZones | configure |
setFeatureFlag, FEATURE_FLAG_NAMES | the useComputedStyleForRects zone option |
type DndZoneAttributes | nothing, onconsider and onfinalize are options |
Still exported and unchanged: alertToScreenReader, TRIGGERS, SOURCES, SHADOW_ITEM_MARKER_PROPERTY_NAME, SHADOW_PLACEHOLDER_ITEM_ID, DRAGGED_ELEMENT_ID, and the type AriaStrings. Still exported, with the changes listed under Type changes: the types Options, DndEvent, DndEventInfo, Item, TransformDraggedElementFunction.
All other zone options keep their names and meaning.