Draggable Elements - Core Concepts

Usage

First, create a DragDropManager instance to orchestrate the drag and drop system. Then use the Draggable class to make elements draggable:

Handles

By default, the entire element can be used to initiate dragging. You can restrict dragging to a specific handle element:

const element = document.createElement('div');
const handle = document.createElement('div');
handle.classList.add('handle');
handle.innerHTML = '⋮'; // Three dots menu icon for drag handle

element.appendChild(handle);

const draggable = new Draggable({
  id: 'draggable-1',
  element,
  handle, // Only allow dragging from the handle
}, manager);

Types

You can assign types to draggable elements to restrict which droppable targets they can be dropped on:

// Assign a type
const draggable = new Draggable({
  id: 'draggable-1',
  element,
  type: 'item', // Only droppables accepting 'item' type will be valid targets
}, manager);

Feedback

You can customize how the element behaves while being dragged using the Feedback plugin’s per-entity configuration:

import {Draggable, DragDropManager, Feedback} from '@dnd-kit/dom';

const draggable = new Draggable({
  id: 'draggable-1',
  element,
  plugins: [Feedback.configure({ feedback: 'clone' })],
}, manager);

Available feedback options:

'default': The original element moves with the drag (best for most cases)
'clone': A copy of the element stays in place while the original moves (good for drag-to-copy)
'move': The element moves without a placeholder (minimal visual feedback)
'none': No visual feedback (useful for custom drag overlays)

API Reference

Arguments

The Draggable class accepts the following arguments:

string | number

required

A unique identifier for this draggable element within the same drag and drop context provider.

element

Element

The DOM element to make draggable. While not required in the constructor, it must be set to enable dragging.

handle

Element

Optionally specify a drag handle element. If not provided, the entire element will be draggable. See drag handles.

type

string | number | Symbol

Optionally assign a type to restrict which droppable targets can accept this element. See types.

plugins

PluginDescriptor[]

An array of plugin descriptors for per-entity plugin configuration. Use Plugin.configure() to create descriptors. See feedback.

disabled

boolean

Set to true to temporarily prevent dragging this element.

modifiers

Modifier[]

An array of modifiers to customize drag behavior.

sensors

Sensors[]

An array of sensors to detect drag interactions.

data

{[key: string]: any}

Optional data to associate with this draggable element, available in event handlers.

effects

() => Effect[]

This is an advanced feature and should not need to be used by most consumers.

You can supply a function that returns an array of reactive effects that can be set up and automatically cleaned up when invoking the destroy() method of this instance.

Properties

The Draggable instance provides these key properties:

id: The unique identifier
element: The main DOM element
handle: The drag handle element (if specified)
type: The assigned type
disabled: Whether dragging is disabled
isDragging: Whether this element is currently being dragged
isDropping: Whether this element is being dropped

Methods

register(): Register this draggable with the manager
unregister(): Remove this draggable from the manager
destroy(): Clean up this draggable instance and remove all listeners