ContextQMD
Back to Dnd Kit

useDraggable

apps/docs/vue/composables/use-draggable.mdx

latest4.7 KB
Original Source

import {CodeSandbox} from '/snippets/sandbox.mdx'; import {draggableStyles} from '/snippets/code.mdx';

<CodeSandbox template="vue" files={{ 'src/App.vue': {code: app, hidden: true}, 'src/Draggable.vue': {code: code, active: true}, 'src/styles.css': {code: draggableStyles, hidden: true}, }} height={260} previewHeight={200} hero />

Usage

The useDraggable composable requires a unique id and an element template ref. It returns reactive computed properties for the drag state.

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

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

<template>
  <button ref="element" :data-dragging="isDragging">
    Drag me
  </button>
</template>

Input

All input properties accept plain values or Vue refs/getters (MaybeRefOrGetter), so they can be reactive.

<ParamField path="id" type="MaybeRefOrGetter<UniqueIdentifier>" required> A unique identifier for this draggable instance. </ParamField> <ParamField path="element" type="MaybeRefOrGetter<HTMLElement | null>" required> A template ref pointing to the draggable element. </ParamField> <ParamField path="handle" type="MaybeRefOrGetter<HTMLElement | null>" optional> A template ref for a drag handle. When set, only this element activates dragging. </ParamField> <ParamField path="disabled" type="MaybeRefOrGetter<boolean>" optional> Whether the draggable is disabled. </ParamField> <ParamField path="plugins" type="MaybeRefOrGetter<PluginDescriptor[]>" optional> An array of plugin descriptors for per-entity plugin configuration. Use `Plugin.configure()` to create descriptors. For example, `Feedback.configure({ feedback: 'clone' })`. </ParamField> <ParamField path="modifiers" type="MaybeRefOrGetter<Modifier[]>" optional> Modifiers to apply to this draggable instance. </ParamField> <ParamField path="sensors" type="MaybeRefOrGetter<Sensor[]>" optional> Sensors to use for this draggable instance. </ParamField> <ParamField path="data" type="MaybeRefOrGetter<Data>" optional> Custom data to attach to this draggable instance. </ParamField>

Output

<ResponseField name="isDragging" type="ComputedRef<boolean>"> Whether this element is currently being dragged (visually). </ResponseField> <ResponseField name="isDropping" type="ComputedRef<boolean>"> Whether this element is in the process of being dropped (animating to final position). </ResponseField> <ResponseField name="isDragSource" type="ComputedRef<boolean>"> Whether this element is the source of the current drag operation. </ResponseField> <ResponseField name="draggable" type="ShallowReadonly<Ref<Draggable>>"> The underlying `Draggable` instance. </ResponseField>

Guides

Rendering a drag overlay

You can render a completely different element while the draggable element is being dragged by using the <DragOverlay> component.

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

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

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

The <DragOverlay> component will only render its children when a drag operation is in progress. This can be useful for rendering a completely different element while the draggable element is being dragged.

<Warning> You should only render the `<DragOverlay>` component once per [DragDropProvider](/vue/components/drag-drop-provider). </Warning>

To render different content depending on which element is being dragged, use the scoped slot to access the drag source:

vue
<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>

export const app = `

<script setup> import { DragDropProvider } from '@dnd-kit/vue'; import Draggable from './Draggable.vue'; import './styles.css'; </script> <template> <DragDropProvider> <Draggable id="draggable" /> </DragDropProvider> </template> `.trim();

export const code = `

<script setup> import { ref } from 'vue'; import { useDraggable } from '@dnd-kit/vue'; const element = ref(null); useDraggable({ id: 'draggable', element }); </script> <template> <button ref="element" class="btn">draggable</button> </template> `.trim();