DragOverlay - Vue

Overview

The DragOverlay component renders a custom overlay element while a drag operation is in progress. This allows you to display a completely different element than the one being dragged, which is useful for rendering a styled clone, a preview, or a simplified representation of the dragged element.

Usage

Import and place the DragOverlay component inside a DragDropProvider. Its children will only be rendered when a drag operation is active.

<script setup>
import {ref} from 'vue';
import {DragDropProvider, DragOverlay, useDraggable} from '@dnd-kit/vue';

const element = ref(null);
useDraggable({id: 'my-item', element});
</script>

<template>
  <DragDropProvider>
    <button ref="element">Drag me</button>
    <DragOverlay>
      <div>I will be rendered while dragging...</div>
    </DragOverlay>
  </DragDropProvider>
</template>

You should only render the DragOverlay component once per DragDropProvider.

Rendering based on the drag source

You can use the scoped slot to access the current drag source and render different content depending on which element is being dragged:

<script setup>
import {DragDropProvider, DragOverlay} from '@dnd-kit/vue';
</script>

<template>
  <DragDropProvider>
    <Draggable id="foo" />
    <Draggable id="bar" />
    <DragOverlay>
      <template #default="{ source }">
        <div>Dragging {{ source.id }}</div>
      </template>
    </DragOverlay>
  </DragDropProvider>
</template>

Customizing the drop animation

By default, when a drag operation ends, the overlay animates back to the position of the source element. You can customize or disable this animation using the drop-animation prop.

<!-- Disable the drop animation -->
<DragOverlay :drop-animation="null">
  <div>No animation on drop</div>
</DragOverlay>

<!-- Customize the animation timing -->
<DragOverlay :drop-animation="{ duration: 150, easing: 'ease-out' }">
  <div>Fast drop animation</div>
</DragOverlay>

Props

tag

string

default: 'div'

The HTML tag to render as the overlay wrapper element.

disabled

boolean

default: false

Whether the drag overlay is disabled. When true, the overlay will not render its children during drag operations.

drop-animation

DropAnimation | null

Customize or disable the drop animation that plays when a drag operation ends.

undefined – use the default animation (250ms ease)
null – disable the drop animation entirely
{duration, easing} – customize the animation timing
(context) => Promise<void> | void – provide a fully custom animation function

Slots

default

Slot

The content to render as the drag overlay. Only rendered when a drag operation is in progress.

Slot props:

source – the Draggable instance that is the source of the current drag operation.