--- title: "The provider" description: "DnDProvider owns every drag under it. It finds the target, starts drags, scrolls, and tells useDnD and useDnDMonitor everything that happens." canonical_url: "https://zizigy.github.io/vue-dnd-kit/docs/guides/provider" --- > Index of every page on this site: [llms.txt](https://zizigy.github.io/vue-dnd-kit/llms.txt) ## One provider for the app ```vue [App.vue] ``` Put one `DnDProvider` high up, in `App.vue` or a layout, and forget about it. Every composable (`makeSortableList`, `makeDraggable`, `useDnD`…) looks for the closest provider above the component it runs in. A composable must run in a component **rendered inside** the provider. Calling it in the component whose own template contains `` throws `No found above this component`: Vue's `inject` only sees ancestors. ## What it owns
Part What the provider does
Input Turns pointer, touch and keyboard input into drags ( sensors , activation ), one drag at a time.
Finding the target Hit-tests the drop targets under the drag ( collision ) and tells them.
The overlay Renders the box that follows the pointer, teleported to body , and lands it on drop.
The selection One set of selected ids, shared by every list and draggable under it.
Auto-scroll Scrolls containers and the window when a drag nears their edges.
The live region Announces pickups, moves, drops and cancels to screen readers.
It renders nothing else: your markup stays as it is. ## Options at a glance Every option has a default that works, so the provider usually takes none. The provider reads its props when it needs them: the demos below switch `collision`, `activation` and `autoScroll` live.
Prop Default What it sets
collision pointerFirst How the target under the drag is chosen. Below .
activation mouse 4 px, touch 200 ms When a press becomes a drag, per pointer kind. Below .
autoScroll on Edge scrolling: { threshold, maxSpeed, acceleration } or false . Below .
haptics a short vibration on touch pickup Vibrations for touch drags, or false . Below .
copyModifier 'Alt' Key that, held while dragging, turns a move into a copy.
modifiers [] Movement rules for every drag: see constraints .
animation / dropAnimation on Items sliding while sorting / the overlay landing: see animations .
animateChanges off Default for lists and trees: animate data changes no drag made.
keyboard Space / Enter, Escape Keyboard keys and step; false turns keyboard drags off. See accessibility .
sensors pointer + keyboard What turns input into drags: see sensors .
overlayTo 'body' Where the overlay is teleported.
overlayFit 'slot' Overlay size: the slot it will land in, or the source's. See the overlay .
overlayTransition a crossfade How the overlay changes from one component to another mid-drag: false , or props. See targets that change the overlay .
overlayClass — Classes for the overlay's content ( [data-dnd-overlay-content] ), the element to animate as a whole: a lift as the drag picks up, a settle as it lands. See the overlay: lift, tilt, settle .
overlayPreviews 5 Multi-drag: how many dragged items get a clone at pickup, or 'all' . See the default overlay .
announcements built-in Screen reader texts, or false .
screenReaderInstructions built-in The text every draggable points to with aria-describedby .
defaultStyles true Injects zero-specificity CSS for drag states: see styling .
The full list with every shape is in the [DnDProvider API](https://zizigy.github.io/docs/api/dnd-provider). The provider also emits `drag-start`, `drag-move`, `drag-over`, `drag-end`, `drag-cancel`, `drag-resume` and `drag-settle`, the same events `useDnDMonitor` hears. ## Read the drag: `useDnD()` `useDnD()` returns the drag as reactive state, in any component under the provider: ```ts import { useDnD } from '@vue-dnd-kit/core'; const { status, active, over, pointer, activation, isAutoScrolling, selection, cancel } = useDnD(); ```
Field What it holds
status 'idle' , 'activating' (a press waiting for its activation), 'dragging' , 'dropping' (no drag runs, but an overlay still lands, or an async onBeforeDrop decides), 'selecting' (a rubber band).
active What is dragged: id , ids (every dragged id, the grabbed one first), items , data , type , element , rect , sensor . null when idle.
over The target under the drag: id , data , element , rect and accepted . null over nothing.
pointer The pointer in viewport coordinates, after modifiers.
activation.progress 0 to 1 while a press waits for its activation: draw a ring with it.
isAutoScrolling Auto-scroll is moving something.
selection The provider's selection: ids , has , add , delete , toggle , set , clear . See multi-drag .
cancel() Cancels the running drag (the items fly back), a charging press, or a selection band.
```vue [DropHint.vue] ``` As soon as a drop is decided, `active`, `over` and `pointer` read `null`, even while the overlay is still landing (`status` reads `'dropping'`). UI derived from them never shows the old drag next to the new data. While an async `onBeforeDrop` waits, the state stays as it was at release. The next drag doesn't wait for a landing: it starts at once, and `status` reads `'dragging'` while the last overlay lands around it. A press on a landing overlay catches it in flight: the drag goes on from where the overlay is. `onDragSettle` tells when a drag's overlay is home. ## Listen to every drag: `useDnDMonitor()` ```ts import { useDnDMonitor } from '@vue-dnd-kit/core'; useDnDMonitor({ onDragStart: ({ active }) => {}, onDragMove: ({ pointer, delta }) => {}, onDragOver: ({ over }) => {}, // the target changed onBeforeDrop: (e) => 'accept', // or 'reject', 'continue', some ids; may be async onDragEnd: ({ active, over, dropped, accepted, position }) => {}, onDragCancel: ({ active }) => {}, onDragResume: ({ active }) => {}, // onBeforeDrop answered 'continue' onDragSettle: ({ active, over }) => {}, // its overlay has landed }); ``` A monitor hears every drag under its provider, wherever it starts: the panel above logs the list's drags without importing it. It stops when the component that called it unmounts.
Event When
onDragStart A drag starts.
onDragMove The drag moves.
onDragOver The target under the drag changes.
onBeforeDrop The drag is released. Its answer decides the drop: see deciding a drop .
onDragEnd The drop went through. Sortable lists have already run their onDrop and written the new order. dropped is false when it ended over no target.
onDragCancel Escape, a drop on a target that refuses it, or an onBeforeDrop that answered 'reject' .
onDragResume onBeforeDrop answered 'continue' : nothing dropped, and the drag goes on.
onDragSettle The drag's overlay has landed (or flown back, or was caught by the next drag), with the event onDragEnd or onDragCancel got. Other drags may have started meanwhile.
Every event carries `active`, `over`, `pointer`, `delta` (the offset from the start), `position` (where the dragged box sits in `over`, see [drag and drop](https://zizigy.github.io/docs/guides/drag-and-drop#leave-it-where-it-was-dropped)) and, for items from a sortable list, `source`. The full shapes are in the [events API](https://zizigy.github.io/docs/api/events). `onDragEnd` is the place for "after the drop" work: saving, clearing the selection, analytics. A list's own `onDrop` runs **before** its write, so it still sees the old order. ## Finding the target Pick a function, then drag the pin or the card over the targets. The badges show how the function ranks them on this frame; the green one is the target. On every frame of a drag, the provider gives `collision` the drop targets in play, and it returns their ids, best first. Five functions come with the library:
Function Ranks Good for
pointerFirst What is under the pointer; when that's nothing, what the dragged box overlaps. The default: precise under the pointer, forgiving in the gaps.
pointerWithin Only what is under the pointer, the innermost first. Precise targets: a gap drops nowhere.
rectIntersection Every target the dragged box overlaps: higher priority , then deeper nesting, then the bigger overlap. Big items over small targets, where the pointer is at the item's edge.
closestCenter Every target, by the distance from the box's center to theirs. Something always wins, even far away: grids and lists of same-size items.
closestCorners Every target, by the distances between the four corners. Columns stacked side by side (kanban), targets of very different heights.
Under the pointer, hit-testing respects what the user sees: of overlapping targets only the one on top is hit (`front`, never `back` where they overlap), and of nested ones the innermost comes first (`subfolder`, then `folder`). ### A function of your own ```ts [magnet.ts] import type { CollisionDetection, Coordinates, Rect } from '@vue-dnd-kit/core'; /** How far the point is from the rect: 0 inside it. */ const gap = (rect: Rect, point: Coordinates) => Math.hypot( Math.max(rect.left - point.x, 0, point.x - rect.right), Math.max(rect.top - point.y, 0, point.y - rect.bottom), ); /** What is under the pointer; in a gap, the nearest target within 40px. */ export const magnet: CollisionDetection = ({ hits, pointer, candidates }) => { if (hits.length) return hits; return candidates .filter((candidate) => gap(candidate.rect, pointer) <= 40) .sort((a, b) => gap(a.rect, pointer) - gap(b.rect, pointer)) .map((candidate) => candidate.id); }; ```
Argument What it holds
pointer The pointer, after modifiers.
overlayRect The dragged box as it is shown, null without an overlay.
candidates Every target in play: id , rect (its visible part, clipped by scroll containers), priority , depth ( 0 at the top, deeper when nested).
hits The targets under the pointer, from hit-testing, best first.
Return an empty array for "no target". Disabled targets, targets inside the dragged items and targets hidden by their scroll containers never reach the function. A target that refuses the drag still competes: over it, `over.accepted` is `false` and a drop is refused (a target inside a sortable item steps aside instead, so the list sorts over it). The demo wraps the chosen function to record its ranking: `(args) => (ranked.value = detect(args))`. The provider damps the switches the function asks for. A target the drag just left can't win again until the pointer has moved 10 px, so boundaries don't flicker. Between the targets nested in a parent (the gaps of a column of cards), the last target stays. ## When a press becomes a drag A press doesn't drag at once. `activation` sets, per pointer kind (`mouse`, `touch`, `pen`), what it waits for: a `distance` in px, a `delay` in ms (with a `tolerance` past which the press gives up, so the page can scroll), or whichever of the two comes first. ```vue ```
Pointer Default
mouse , pen { distance: 4 } : a click stays a click. A mouse press on a handle starts at once, and is still a click if it doesn't move.
touch { delay: 200, tolerance: 5 } : a long press, so lists keep scrolling under a finger.
A kind you leave out keeps its default. A draggable's own `activation` wins over a [drag area's](https://zizigy.github.io/docs/guides/constraints), which wins over the provider's. While a press waits, `useDnD().status` is `'activating'` and `activation.progress` runs from `0` to `1`; Escape or `useDnD().cancel()` gives it up. Try the constraints live, and draw a long-press ring from the progress, in [sensors](https://zizigy.github.io/docs/guides/sensors#activation-constraints). ## Auto-scroll Drag a channel toward the top or the bottom of the list. The green bands are the edge zones: the deeper into one, the faster the list scrolls. Any element with `overflow: auto` or `scroll` scrolls by itself, and so does the window. The provider scrolls the container under the pointer first, then its ancestors, then the window.
Option Default What it sets
threshold 0.2 The edge zone, as a fraction of the container's size, between 24 and 96 px.
acceleration 10 The speed at the very edge, in px per frame. It grows with the square of the depth into the zone, so the start is slow and precise.
maxSpeed 25 The top speed. Past the edge (the pointer outside the container), the speed keeps growing up to it.
`:auto-scroll="false"` turns it off. A direction scrolls only once the pointer has moved that way, so an item picked up near an edge doesn't scroll by itself. Lists, trees and [drag areas](https://zizigy.github.io/docs/guides/constraints) take an `autoScroll` of their own for their container: ```ts makeSortableList(list, { items: channels, autoScroll: { maxSpeed: 10 } }); ``` Keyboard drags never auto-scroll: they scroll the item into view instead. `isAutoScrolling` (from `useDnD()`, or a drag area) is `true` while something scrolls. ## Haptics and the copy key A touch drag vibrates briefly when it starts. `:haptics="false"` turns that off; an object sets each vibration: ```vue ```
Key Vibrates when Default
start The long press turns into a drag. true (10 ms)
enter The drag enters a target that accepts it. off
drop The drop goes through. off
refuse The drop is refused and the items fly back. off
Each takes `true` (the default pattern), a length in ms, an on/off pattern, or `false`. Only drags started by touch vibrate, and iOS Safari can't vibrate at all. `copyModifier` is the key that, held during a drag between lists, turns the move into a copy: `'Alt'` by default, any `KeyboardEvent.key`, or `null` for none. The list the items come from needs a `clone` function; see [lists that share items](https://zizigy.github.io/docs/guides/shared-lists). ## Several providers Most apps need exactly one. Put the wishlist under its own provider, then try to move a book across: it can't leave its provider, and the outer monitor stops hearing the wishlist. ```vue ``` - Providers are independent: a drag never crosses from one to another. - Nested providers are allowed. The **closest owner wins**: an item belongs to the nearest provider above it, and the outer provider ignores it. - Each provider has its own selection, overlay, live region and monitors. A second provider makes sense only for a part of the page that needs its own provider-wide settings (collision, keyboard keys, announcements) and whose items never leave it. If items can't move between two parts of your page, check that they don't sit under two providers. Rules for one part of the page (a board that snaps, a feed with a longer touch press, a panel where nothing drags) don't need a provider of their own: ```ts makeDragArea(board, { modifiers: [snapToGrid(20)], activation: { touch: { delay: 400 } } }); ``` Its items stay in the app's provider and can still move anywhere. See [constraints](https://zizigy.github.io/docs/guides/constraints). An app mounted elsewhere, inside a shadow root or as a separate Vue app, can join an existing provider: pass `useDnDContext()` to `provideDnDContext(app, context)` before mounting it. Hit-testing and the overlay work across shadow roots. ## SSR and Nuxt The provider is SSR-safe. Lists and items render on the server like any other markup. The overlay and the live region are teleported and mount on the client only, so they never cause a hydration mismatch. Default ids come from Vue's `useId()` and match between server and client. In Nuxt, the module registers `DnDProvider` globally and auto-imports the composables: see [installation](https://zizigy.github.io/docs/getting-started/installation#nuxt). ## Sitemap See the full [sitemap](https://zizigy.github.io/vue-dnd-kit/sitemap.md) for all pages.