Skip to main content

​
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.