Docs/API

makeDragArea

Rules for the drags that start inside an element — an axis, bounds, a grid, auto-scroll, activation — under one app-wide provider.

Edit this page

function makeDragArea(  target: MaybeElementRef,  options?: DragAreaOptions,): DragAreaReturn;

Makes an element a drag area: the drags that start inside it (draggables and sortable items) follow its rules, see DragAreaOptions. One provider can then serve the whole app, with boards, canvases and feeds that drag their own way. The closest area wins when areas are nested.

const board = useTemplateRef<HTMLElement>('board');
makeDragArea(board, { restrictToArea: true, modifiers: [snapToGrid(24)] });

Inner areas inherit disabled; every other rule comes from the closest area. See Axes, bounds and grids.

The chips inside the area follow its rules; the one outside it drags freely.

Live Switch the area's rules, then drag a chip inside it

Loading the demo…

<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import AreaDesk from './AreaDesk.vue';
</script>

<template>
  <!-- One provider for everything: the area changes the rules only for the drags that start in it. -->
  <DnDProvider>
    <AreaDesk />
  </DnDProvider>
</template>

Options

Options of makeDragArea: rules for the drags that start inside the area's element (draggables and sortable items alike), so one provider can serve the whole app while parts of the page drag their own way. The closest area wins when areas are nested.

Every option takes a value, a ref or a getter and is read when it is needed: when a press starts (activation, disabled) or when the drag starts.

axis?

'x' | 'y'value · ref · getter

Locks the drags to one axis, after the modifiers. A draggable's own axis (or its list's) wins.

modifiers?

Modifier[]value · ref · getter

Modifiers for the drags, after the provider's and before the draggable's own (or its list's): e.g. [snapToGrid(20)] for a board.

restrictToArea?

booleanvalue · ref · getter

true: the drags stay inside the area's element (after the modifiers, before the axis lock).

autoScroll?

boolean | AutoScrollOptionsvalue · ref · getter

Overrides the provider's autoScroll for the area's scroll container: the element itself, or its closest scrollable ancestor. false turns it off there. Unlike the other options it applies to every drag that scrolls the container, wherever it started.

activation?

ActivationOptionsvalue · ref · getter

Activation of the drags per pointer kind, between the draggable's own (which wins) and the provider's: e.g. a longer touch press in a scrolling feed.

disabled?

booleanvalue · ref · getter

true: no drag starts in the area, nor in the areas inside it (unlike the other options, which come from the closest area). Its draggables report aria-disabled.

Returns

What makeDragArea returns.

isDragging

ComputedRef<boolean>

A drag that started in this area is running (until its drop is decided).

isAutoScrolling

ComputedRef<boolean>

Auto-scroll is moving the area's scroll container (the element, or its closest scrollable ancestor).