@dnd-kit/abstract

Framework-agnostic core API for building drag and drop interfaces

@dnd-kit/abstract is the foundational package of dnd-kit that provides a framework-agnostic implementation of drag and drop functionality. It can be used to build drag and drop interfaces in any JavaScript environment.

Overview

The abstract package provides the core primitives and APIs for:

• Drag and Drop Management: Centralized orchestration of drag operations
• Entities: Draggable and Droppable primitives for defining interactive elements
• Sensors: Pluggable input handlers for mouse, touch, keyboard, and custom interactions
• Modifiers: Transform drag behavior with constraints, snapping, and custom logic
• Plugins: Extend functionality with reusable, composable behaviors
• Collision Detection: Flexible algorithms for determining drop targets
• Event System: Comprehensive event lifecycle hooks

Installation

npm install @dnd-kit/abstract

Core Exports

Manager

DragDropManager

Central orchestrator for all drag and drop operations

Entities

Draggable

Entities that can be dragged

Droppable

Entities that can receive draggables

Extensibility

Sensors

Input handlers for drag interactions

Modifiers

Transform drag behavior

Plugins

Extend drag and drop functionality

Type Definitions

UniqueIdentifier

Type representing a unique identifier for entities.

type UniqueIdentifier = string | number;

Data

Type representing arbitrary data associated with an entity.

type Data = Record<string, any>;

Type

Type representing the type/category of an entity.

type Type = Symbol | string | number;

Used to categorize entities and implement type-based filtering or matching between draggables and droppables.

Event System

The abstract package provides a comprehensive event system for monitoring drag and drop operations:

Event Types

collision

Fired when collisions are detected between draggables and droppables.

type CollisionEvent = Preventable<{
  collisions: Collisions;
}>;

beforedragstart

Fired before a drag operation starts. Can be prevented.

type BeforeDragStartEvent = Preventable<{
  operation: DragOperationSnapshot;
  nativeEvent?: Event;
}>;

dragstart

Fired when a drag operation starts.

type DragStartEvent = {
  operation: DragOperationSnapshot;
  nativeEvent?: Event;
  cancelable: false;
};

dragmove

Fired when the dragged entity moves.

type DragMoveEvent = Preventable<{
  operation: DragOperationSnapshot;
  to?: Coordinates;
  by?: Coordinates;
  nativeEvent?: Event;
}>;

dragover

Fired when a draggable hovers over a droppable.

type DragOverEvent = Preventable<{
  operation: DragOperationSnapshot;
}>;

dragend

Fired when a drag operation ends.

type DragEndEvent = {
  operation: DragOperationSnapshot;
  nativeEvent?: Event;
  canceled: boolean;
  suspend(): {resume(): void; abort(): void};
};

Using Events

const manager = new DragDropManager();

// Listen to drag start
manager.monitor.addEventListener('dragstart', (event, manager) => {
  console.log('Drag started:', event.operation.source);
});

// Prevent drag move
manager.monitor.addEventListener('dragmove', (event) => {
  if (someCondition) {
    event.preventDefault();
  }
});

// Handle drag end with suspension
manager.monitor.addEventListener('dragend', (event) => {
  if (event.canceled) {
    console.log('Drag was canceled');
  } else {
    // Suspend the operation for async cleanup
    const {resume, abort} = event.suspend();
    
    performAsyncCleanup()
      .then(resume)
      .catch(abort);
  }
});

Collision Detection

The package provides utilities for collision detection:

CollisionPriority

Priority levels for collision detection.

enum CollisionPriority {
  Lowest,
  Low,
  Normal,
  High,
  Highest,
}

CollisionType

Types of collision detection.

enum CollisionType {
  Collision,
  ShapeIntersection,
  PointerIntersection,
}

Collision Interface

interface Collision {
  id: UniqueIdentifier;        // Droppable identifier
  priority: CollisionPriority | number;
  type: CollisionType;
  value: number;                // Collision strength
  data?: Record<string, any>;   // Additional data
}

CollisionDetector

Function type for custom collision detection.

type CollisionDetector = <T extends Draggable, U extends Droppable>(
  input: CollisionDetectorInput<T, U>
) => Collision | null;

interface CollisionDetectorInput<T, U> {
  droppable: U;
  dragOperation: DragOperation<T, U>;
}

sortCollisions

Utility function to sort collisions by priority and value.

function sortCollisions(collisions: Collisions): Collisions

Customizable Type

Many configuration options accept a Customizable type that allows either a direct value or a function that receives defaults:

type Customizable<T> = T | ((defaults: T) => T);

Examples

// Direct value (replaces defaults)
const manager = new DragDropManager({
  plugins: [MyPlugin]
});

// Function (receives and extends defaults)
const manager = new DragDropManager({
  plugins: (defaults) => [...defaults, MyPlugin]
});

resolveCustomizable

Utility function to resolve customizable values:

function resolveCustomizable<T>(
  value: Customizable<T> | undefined,
  defaults: T
): T

Renderer

Type for handling visual rendering of drag operations.

type Renderer = {
  rendering: Promise<void>;
};

The renderer’s rendering promise resolves when the current render cycle is complete, allowing for coordination between drag operations and visual updates.

Architecture

The abstract package follows a plugin-based architecture:

Next Steps

DragDropManager

Learn about the central manager API

Draggable

Create draggable entities

Droppable

Create droppable entities

Sensors

Implement input handlers