DragDropProvider

Enable drag and drop interactions in your React application.

Overview

The DragDropProvider component creates a context that enables drag and drop interactions for its children. It manages the drag and drop state and coordinates between draggable and droppable elements.

Basic Usage

Wrap your application or a section with DragDropProvider:

import {DragDropProvider} from '@dnd-kit/react';

function App() {
  return (
    <DragDropProvider>
      <YourDraggableContent />
    </DragDropProvider>
  );
}

Event Handling

Listen to drag and drop events to respond to user interactions:

function App() {
  return (
    <DragDropProvider
      onBeforeDragStart={(event) => {
        // Optionally prevent dragging
        if (shouldPreventDrag(event.operation.source)) {
          event.preventDefault();
        }
      }}
      onDragStart={({operation}) => {
        console.log('Started dragging', operation.source.id);
      }}
      onDragMove={({operation}) => {
        const {position} = operation;
        console.log('Current position:', position);
      }}
      onDragOver={({operation}) => {
        const {source, target} = operation;
        console.log(`${source.id} is over ${target?.id}`);
      }}
      onDragEnd={({operation}) => {
        const {source, target} = operation;
        if (target) {
          console.log(`Dropped ${source.id} onto ${target.id}`);
        }
      }}
    >
      <YourDraggableContent />
    </DragDropProvider>
  );
}

Multiple Contexts

You can create multiple independent drag and drop contexts:

function App() {
  return (
    <div>
      <DragDropProvider>
        <FileList /> {/* Files can only be dropped in this context */}
      </DragDropProvider>

      <DragDropProvider>
        <TaskList /> {/* Tasks can only be dropped in this context */}
      </DragDropProvider>
    </div>
  );
}

Configuration

Customize behavior with plugins, sensors, and modifiers. Each accepts either an array (which replaces the defaults) or a function that receives the defaults.

Extending defaults

Use the function form to add to or configure the defaults without replacing them:

import {DragDropProvider} from '@dnd-kit/react';
import {Feedback} from '@dnd-kit/dom';
import {RestrictToWindow} from '@dnd-kit/dom/modifiers';

function App() {
  return (
    <DragDropProvider
      // Add a plugin alongside defaults
      plugins={(defaults) => [
        ...defaults,
        Feedback.configure({ dropAnimation: null }),
      ]}
      // Add a modifier
      modifiers={(defaults) => [...defaults, RestrictToWindow]}
    >
      <YourDraggableContent />
    </DragDropProvider>
  );
}

Replacing defaults

Pass an array to fully replace the defaults:

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

function App() {
  return (
    <DragDropProvider
      sensors={[
        PointerSensor,
        KeyboardSensor,
      ]}
      plugins={[
        AutoScroller,
        Accessibility,
      ]}
      modifiers={[
        RestrictToWindow,
      ]}
    >
      <YourDraggableContent />
    </DragDropProvider>
  );
}

API Reference

Props

children · ReactNode · required

Content where drag and drop should be enabled.

manager · DragDropManager

Optional custom manager instance. If not provided, one will be created.

Events

onBeforeDragStart · (event: BeforeDragStartEvent, manager: DragDropManager) => void

Called before dragging starts. Call event.preventDefault() to cancel.

onDragStart · (event: DragStartEvent, manager: DragDropManager) => void

Called when dragging begins.

onDragMove · (event: DragMoveEvent, manager: DragDropManager) => void

Called when the dragged element moves.

onDragOver · (event: DragOverEvent, manager: DragDropManager) => void

Called when dragging over a droppable target. Call event.preventDefault() to prevent the default behavior of plugins that respond to this event.

onDragEnd · (event: DragEndEvent, manager: DragDropManager) => void

Called when dragging ends, whether dropped on a target or not.

onCollision · (event: CollisionEvent, manager: DragDropManager) => void

Called when collisions are detected. Call event.preventDefault() to prevent automatic target selection.

Event object structure

All event handlers receive an event object and the manager instance. The most commonly used event, onDragEnd, has this shape:

onDragEnd={(event, manager) => {
  event.operation.source   // The dragged element (Draggable), or null
  event.operation.target   // The drop target (Droppable), or null
  event.operation.source.id     // Unique identifier of the dragged element
  event.operation.target?.id    // Unique identifier of the drop target
  event.operation.position      // { current: {x, y}, initial: {x, y} }
  event.operation.status        // Status of the drag operation
  event.canceled                // true if the drag was cancelled (e.g. Escape key)
  event.nativeEvent             // The underlying browser event, if available
}}

For sortable elements, use the isSortable type guard to access sortable-specific properties:

import {isSortable} from '@dnd-kit/react/sortable';

onDragEnd={(event) => {
  const {source} = event.operation;

  if (isSortable(source)) {
    source.index         // Current position
    source.initialIndex  // Position when the drag started
    source.group         // Current group (for multi-list)
    source.initialGroup  // Group when the drag started
  }
}}

Configuration

sensors · Sensor[] | (defaults: Sensor[]) => Sensor[]

Sensors for detecting user input. Pass an array to replace defaults, or a function to extend them.

plugins · Plugin[] | (defaults: Plugin[]) => Plugin[]

Plugins to extend functionality. Pass an array to replace defaults, or a function to extend them.

modifiers · Modifier[] | (defaults: Modifier[]) => Modifier[]

Modifiers to customize drag behavior. Pass an array to replace defaults, or a function to extend them.