Docs/API

makeDraggable

Makes an element draggable — free dragging, or into the drop targets that accept it.

function makeDraggable<TData = unknown>(  target: MaybeElementRef,  options?: DraggableOptions<TData>,): DraggableReturn;

Makes an element draggable. Free drag by default; sortable lists build on top of it.

const el = useTemplateRef<HTMLElement>('el');
const { isDragging } = makeDraggable(el, { id: 'card', type: 'card', data: { title } });

See Drag and drop. Sortable items are draggables too: makeSortableItem takes the same options and more.

Live Drag each card. Let go, and it goes back

Loading the demo…

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

<template>
  <!-- No drop target here: let go, and each card goes back where it was. -->
  <DnDProvider>
    <div class="cards">
      <DragCard title="Grab it anywhere" code="makeDraggable(el)" />
      <DragCard title="Grab the handle" code="{ handle: grip }" handle />
      <DragCard title="It moves itself" code="{ overlay: false }" self />
      <DragCard title="Not now" code="{ disabled: true }" disabled />
    </div>
  </DnDProvider>
</template>

<style scoped>
.cards {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 220px));
  gap: 14px;
}

@media (max-width: 480px) {
  .cards {
    grid-template-columns: minmax(0, 1fr);
  }
}
</style>

Options

Options of makeDraggable. Every option but canDrag takes a value, a ref or a getter (overlay, dropAnimation: a value or a ref) and is read when it is needed, so a change applies to the next drag at the latest.

id?

Keyvalue · ref · getter

Stable id. Pass a getter in virtual lists, where elements are recycled. Default: useId(), stable between server and client render but new for every component instance.

data?

TDatavalue · ref · getter

Anything the drag should carry: events and drop targets read it as active.data.

label?

stringvalue · ref · getter

What people call it: screen reader texts say it instead of the id (Picked up Tomato). Events carry it as active.label and in items.

type?

string | string[]value · ref · getter

Its type or types, matched by the accept rules of drop targets. Without one it fits any target.

disabled?

booleanvalue · ref · getter

true: it can't be dragged (it reports aria-disabled).

handle?

MaybeElement | stringvalue · ref · getter

Element or selector inside the draggable that starts the drag (and gets the attributes).

activation?

ActivationOptionsvalue · ref · getter

Overrides the provider's activation. Read when a press starts.

canDrag?

(event: PointerEvent | KeyboardEvent) => boolean

Extra gate, e.g. drag only while a key is held.

overlay?

boolean | Componentvalue · ref

true (default): an overlay follows the pointer, rendered by the provider's #overlay slot or as a clone of the element. A component: the overlay renders it with OverlayProps, before the slot. false: no overlay, the element itself moves via the returned transform. A value or a ref (a function is a functional component, so (props) => <Card {...props} /> works). Whether there is an overlay is decided when the drag starts; a ref switched mid-drag swaps the component at once (see the provider's overlayTransition). A drop target's overOverlay wins while the drag is over it. The clone leaves out the press effects of UI kits (ripples) and any element inside marked data-dnd-no-clone.

dropAnimation?

DropAnimationvalue · ref

How the overlay lands when a drag of this element ends, instead of the provider's dropAnimation; a drop target's overDropAnimation wins. A value or a ref (a function is the animation), read at the drop.

modifiers?

Modifier[]value · ref · getter

Modifiers for drags that start here, applied after the provider's modifiers: e.g. [restrictToVerticalAxis] for one element on a page where other drags move freely. Read when the drag starts.

axis?

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

Locks drags that start here to one axis: 'x' moves only horizontally, 'y' only vertically. The lock comes after modifiers (restrictToHorizontalAxis / restrictToVerticalAxis last), so it holds whatever they do. Read when the drag starts.

keyboardMode?

'pixels' | 'droppables'value · ref · getter

Arrow keys in free drags: move by pixels (default) or jump between accepting drop targets. Read on every arrow press.

attributes?

booleanvalue · ref · getter

Set role/tabindex/aria-* attributes (default true), never overriding the user's own. The provider's instructions id joins an existing aria-describedby as one more token (a UI kit tooltip on the same element keeps its own), and only that token is ever removed. Live: turning it off removes what the library set.

native?

boolean | NativeDragOptionsvalue · ref · getter

A mouse drag of it is the browser's own drag, which can leave the page: onto the desktop, into another app or tab, into another window of the app. On the page it works as usual (targets, lists that make room), but the browser draws the dragged image instead of the overlay. Touch and keyboard drags stay the library's. true carries the label as text. Read when a press starts. canDrag is asked at the press; the browser decides how far a mouse moves before its drag starts (activation doesn't apply to it).

Returns

What makeDraggable returns.

ComputedRef<Key>

The draggable's id: the id option, or the one made for it.

isDragging

ComputedRef<boolean>

It is being dragged (also as another item of a multi-drag), or its overlay is still landing.

transform

ComputedRef<Coordinates | null>

Offset to apply when overlay: false: the drag's, less how far the content the element is in has moved since the start (the page or a container scrolled), so the element stays under the pointer.

selected

WritableComputedRef<boolean>

It is in the provider's selection: a drag of one selected item carries them all. Set it to select or deselect.

Out of the page

What a native drag carries out of the page. See files and other apps.

A draggable or sortable item that a mouse can drag out of the page (native): onto the desktop, into another app, another tab, another window of the app.

data?

(active: Active) => Record<string, string>

What other apps and pages get: text by MIME type, as { 'text/plain': title, 'text/uri-list': url }. Read when the drag starts. Sortable items also carry themselves, for the lists of their group in another window of the app.

effect?

What the drag lets the place it is dropped on do (effectAllowed). Default 'copyMove': a move takes the items out of their list here, a copy leaves them.