Draggable

Entities that can be dragged in drag and drop operations

Draggable represents an entity that can be dragged in a drag and drop operation. It extends the base Entity class with draggable-specific functionality including sensor-based interaction handling, modifier-based behavior transformation, and status tracking.

Constructor

Creates a new draggable entity.

const draggable = new Draggable<T, U>(input, manager);

input · DraggableInput<T> · required

Configuration object for the draggable.

Show DraggableInput properties

id · UniqueIdentifier · required

Unique identifier for this draggable entity.

id: 'item-1'
// or
id: 123

data · T

Arbitrary data associated with this entity.

data: {
  label: 'Drag me',
  category: 'important',
  metadata: {...}
}

type · Type

Type/category for this draggable. Used for filtering and matching with droppables.

type: 'card'
// or
type: Symbol('card')

sensors · Sensors

Array of sensor constructors or descriptors specific to this draggable. These override the manager’s sensors for this entity.

sensors: [PointerSensor, KeyboardSensor]

modifiers · Modifiers

Array of modifier constructors or descriptors specific to this draggable. These override the manager’s modifiers for this entity.

modifiers: [SnapModifier.configure({gridSize: 20})]

alignment · Alignment

Alignment configuration for positioning the draggable.

alignment: {x: 0.5, y: 0.5} // Center alignment

plugins · Plugins

Per-entity plugin configuration descriptors.

plugins: [MyPlugin.configure({option: 'value'})]

disabled · boolean · default: "false"

Whether the entity should initially be disabled.

register · boolean · default: "true"

Whether to automatically register with the manager when created.

effects · () => Effect[]

Array of effects that are set up when registered and cleaned up when unregistered.

manager · U | undefined · required

The drag and drop manager instance, or undefined for unmanaged entities.

T · extends Data · default: "Data"

Type parameter for the data associated with this draggable.

U · extends DragDropManager<any, any> · default: "DragDropManager<any, any>"

Type parameter for the manager type.

Properties

Inherited from Entity

id · UniqueIdentifier

The unique identifier of the entity. Can be updated dynamically.

draggable.id = 'new-id';

data · T

The data associated with the entity.

draggable.data = {label: 'Updated label'};

manager · U | undefined

The drag and drop manager instance.

draggable.manager = newManager;

disabled · boolean

Whether the entity is disabled.

draggable.disabled = true;

Draggable-Specific

type · Type | undefined

The type/category of the draggable entity.

draggable.type = 'card';

sensors · Sensors | undefined

The sensors associated with this draggable entity.

modifiers · Modifiers | undefined

The modifiers associated with this draggable entity.

draggable.modifiers = [SnapModifier];

alignment · Alignment | undefined

The alignment configuration for this draggable entity.

plugins · Plugins | undefined

Per-entity plugin configuration descriptors.

status · DraggableStatus

The current status of the draggable entity.

type DraggableStatus = 'idle' | 'dragging' | 'dropping';

• idle - Not being dragged
• dragging - Currently being dragged
• dropping - Currently being dropped

Computed Properties

isDragSource

isDragSource · boolean

Checks if this draggable is the source of the current drag operation.

if (draggable.isDragSource) {
  console.log('This item is being dragged');
}

Returns true if this entity’s ID matches the current drag operation’s source ID.

isDragging

isDragging · boolean

Checks if this draggable is currently being dragged.

if (draggable.isDragging) {
  console.log('Actively dragging');
}

Returns true if the status is 'dragging' and this is the drag source.

isDropping

isDropping · boolean

Checks if this draggable is currently being dropped.

if (draggable.isDropping) {
  console.log('Drop animation in progress');
}

Returns true if the status is 'dropping' and this is the drag source.

Methods

pluginConfig()

Looks up per-entity options for a given plugin constructor.

const options = draggable.pluginConfig(MyPlugin);

plugin · PluginConstructor · required

The plugin constructor to look up configuration for.

return · PluginOptions | undefined

The plugin options if configured for this entity, undefined otherwise.

Inherited from Entity

register()

Registers the entity with its manager.

const cleanup = draggable.register();

return · CleanupFunction | void

A cleanup function to unregister the entity, or void if no manager is set.

unregister()

Unregisters the entity from its manager.

draggable.unregister();

destroy()

Cleans up the entity when it’s no longer needed.

draggable.destroy();

This method unregisters the entity from the manager and cleans up any resources.

Usage Examples

Basic Draggable

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

const manager = new DragDropManager();

const draggable = new Draggable(
  {
    id: 'item-1',
    data: {label: 'Drag me', index: 0}
  },
  manager
);

With Type

const draggable = new Draggable(
  {
    id: 'card-1',
    type: 'card', // Only droppable zones accepting 'card' type will accept this
    data: {title: 'Task 1', status: 'todo'}
  },
  manager
);

With Custom Sensors

import {PointerSensor, KeyboardSensor} from '@dnd-kit/dom/sensors';

const draggable = new Draggable(
  {
    id: 'item-1',
    sensors: [PointerSensor, KeyboardSensor],
    data: {label: 'Accessible drag item'}
  },
  manager
);

With Modifiers

import {SnapModifier} from '@dnd-kit/abstract/modifiers';

const draggable = new Draggable(
  {
    id: 'item-1',
    modifiers: [SnapModifier.configure({gridSize: 20})],
    data: {label: 'Snaps to grid'}
  },
  manager
);

With Alignment

const draggable = new Draggable(
  {
    id: 'item-1',
    alignment: {x: 0.5, y: 0.5}, // Center alignment
    data: {label: 'Centered'}
  },
  manager
);

Checking Status

const draggable = new Draggable({id: 'item-1'}, manager);

// Check if being dragged
if (draggable.isDragging) {
  console.log('This item is being dragged');
}

// Check status value
switch (draggable.status) {
  case 'idle':
    console.log('Ready to drag');
    break;
  case 'dragging':
    console.log('Dragging in progress');
    break;
  case 'dropping':
    console.log('Drop animation');
    break;
}

Dynamic Updates

const draggable = new Draggable({id: 'item-1'}, manager);

// Update data
draggable.data = {label: 'Updated label'};

// Disable dragging
draggable.disabled = true;

// Change type
draggable.type = 'special-card';

// Update modifiers
draggable.modifiers = [NewModifier];

TypeScript Types

interface CardData {
  title: string;
  description: string;
  priority: 'low' | 'medium' | 'high';
}

const draggable = new Draggable<CardData>(
  {
    id: 'card-1',
    data: {
      title: 'My Task',
      description: 'Complete this task',
      priority: 'high'
    }
  },
  manager
);

// TypeScript knows the shape of data
const title = draggable.data.title; // string

Manual Registration

// Create without auto-registration
const draggable = new Draggable(
  {
    id: 'item-1',
    register: false
  },
  manager
);

// Register later
const cleanup = draggable.register();

// Unregister
cleanup();
// or
draggable.unregister();

With Effects

const draggable = new Draggable(
  {
    id: 'item-1',
    effects: () => [
      // Effect runs when entity is registered
      () => {
        console.log('Draggable registered');
        
        // Cleanup runs when unregistered
        return () => {
          console.log('Draggable unregistered');
        };
      }
    ]
  },
  manager
);

Plugin Configuration

import {MyPlugin} from './my-plugin';

const draggable = new Draggable(
  {
    id: 'item-1',
    plugins: [
      MyPlugin.configure({
        option1: 'value1',
        option2: true
      })
    ]
  },
  manager
);

// Retrieve plugin config
const config = draggable.pluginConfig(MyPlugin);
console.log(config); // {option1: 'value1', option2: true}

See Also

• DragDropManager - Managing drag operations
• Droppable - Creating drop targets
• Sensors - Handling user input
• Modifiers - Transforming drag behavior