dndzone and options
The dndzone attachment and the options of a dndzone or a dragHandleZone.
A zone takes a function that returns its options, and reads it again whenever the state it reads changes. Every option except items is optional. The getting started page shows a full example, and how it works explains the events.
dndzone
Turns any container into a dnd zone and all of its direct children into draggables. Supports mouse, touch and keyboard interactions. Calls the onconsider and onfinalize options, which the container is expected to react to by reassigning its list of items, which then feeds back into the zone through the options getter.
function dndzone<T extends object>(getOptions: () => Options<T>): Attachment<HTMLElement> Options
dragHandleZone takes the same options. See drag handles.
The options of a dndzone or a dragHandleZone, returned by the getter the zone is given.
interface Options<T extends object = Item> | Name | Type | Default | Description |
|---|---|---|---|
items | T[] | - | The list of items the zone renders, the one used in its #each block. Each item needs a unique id under the id
key. Required. |
type? | string | "--any--" | The type of the zone. Items dragged from it can only be dropped in zones of the same type. Zones without a type share one base type. |
flipDurationMs? | number | 0 | The duration in milliseconds of the zone's flip animation, if it animates its items with flip (recommended), so the drag and the animation do not conflict. It also sets the duration of the drop animation. |
dragDisabled? | boolean | false | Turns dragging off for this zone's items: with the pointer and with the keyboard. With dragHandleZone, it turns
off this zone's handles only. |
morphDisabled? | boolean | false | Whether the dragged element keeps its own shape instead of taking the size and styles of the placeholder item in the zone it hovers over. |
dropFromOthersDisabled? | boolean | false | Stops the zone from accepting items dragged from other zones. Its own items can still be dragged and dropped within it. |
zoneTabIndex? | number | 0 | The tabindex of the zone element when no keyboard drag is in progress. |
zoneItemTabIndex? | number | 0 | The tabindex of the zone's items when no keyboard drag is in progress. |
dropTargetClasses? | string[] | [] | Classes added to the zone while a drag is in progress that can drop into it, and removed when the drag ends. |
dropTargetStyle? | Record<string, string> | { outline: "rgba(255, 255, 102, 0.7) solid 2px" } | Inline styles set on the zone while a drag is in progress that can drop into it, and removed when the drag ends. The keys are CSS property names. |
transformDraggedElement? | TransformDraggedElementFunction<T> | a function that does nothing | Called during a pointer drag each time the zone renders the dragged item's placeholder, to change the look of the dragged element. It runs after the element morphs, so its changes win. |
autoAriaDisabled? | boolean | false | Stops the zone from setting ARIA roles and the aria-describedby instructions on itself and its items, and from
announcing keyboard drags to screen readers. Set it when you provide your own. |
centreDraggedOnCursor? | boolean | false | Centres the dragged element on the cursor when a pointer drag starts, instead of keeping the offset at which the item was grabbed. |
dropAnimationDisabled? | boolean | false | Drops the item in place at the end of a pointer drag, without animating it to its new position. |
delayTouchStart? | boolean | number | false | How long a touch has to be held before it starts a drag, so that a swipe still scrolls the page. true waits
80 ms, a number waits that many milliseconds, and false starts the drag as soon as the touch moves. |
useCursorForDetection? | boolean | false | Uses the cursor position instead of the centre of the dragged element to find the zone and the index the item is over. |
useComputedStyleForRects? | boolean | false | Sizes the dragged clone from computed styles instead of bounding rects: it copies the computed width, height and box-sizing from the item when the drag starts, and from the shadow element while morphing. A workaround for issue 454 (a browser bug): these rect values take time to update in a grid layout. Setting it can cause strange behaviour in non-grid zones, see issue 470. |
onconsider? | (event: DndEvent<T>) => void | - | Called while the user drags, with the items the zone should render now. |
onfinalize? | (event: DndEvent<T>) => void | - | Called with the items the zone should keep: at the end of a pointer drag, and each time a keyboard drag moves
the item. A keyboard drag ends with an onconsider call whose trigger is TRIGGERS.DRAG_STOPPED. |
useComputedStyleForRects replaces the USE_COMPUTED_STYLE_INSTEAD_OF_BOUNDING_RECT feature flag of svelte-dnd-action. It is set per zone, and most apps do not need it.