Migration guide

A comprehensive guide to migrate from @dnd-kit/core to @dnd-kit/react

1. Update dependencies

   Update your package.json and install the new packages:

     "dependencies": {
       "@dnd-kit/core": "^x.x.x",      
       "@dnd-kit/sortable": "^x.x.x",  
       "@dnd-kit/utilities": "^x.x.x", 
       "@dnd-kit/react": "^x.x.x",     
       "@dnd-kit/helpers": "^x.x.x",   
     }
   

   After updating your package.json, install the new dependencies with your package manager of choice.

2. Migrate context provider

   Update your context provider. The new DragDropProvider replaces the legacy DndContext:

   Before

   import {DndContext} from '@dnd-kit/core';
   
   function App() {
     return (
       <DndContext
         onDragStart={({active}) => {
           console.log(`Started dragging ${active.id}`);
         }}
         onDragEnd={({active, over}) => {
           if (over) {
             console.log(`Dropped ${active.id} over ${over.id}`);
           }
         }}
         onDragCancel={({active}) => {
           console.log(`Cancelled dragging ${active.id}`);
         }}
       >
         <YourComponents />
       </DndContext>
     );
   }
   

   The new provider gives you access to the manager instance in event handlers, enabling more advanced control over the drag and drop system.

3. Update draggable components

   Update your draggable components using the new useDraggable hook:

   Before

   function DraggableItem({id}) {
     const {
       attributes,
       listeners,
       setNodeRef,
       transform
     } = useDraggable({
       id
     });
   
     return (
       <div
         ref={setNodeRef}
         {...listeners}
         {...attributes}
         style={{
           transform: CSS.Transform.toString(transform)
         }}
       >
         Item {id}
       </div>
     );
   }
   
4. Update droppable components

   Update your droppable components using the new useDroppable hook:

   Before

   function Dropzone() {
     const {setNodeRef, isOver} = useDroppable({
       id: 'drop-zone'
     });
   
     return (
       <div
         ref={setNodeRef}
         style={{
           background: isOver ? 'lightblue' : 'white'
         }}
       >
         Drop here
       </div>
     );
   }
   
5. Update drag overlay

   The DragOverlay component has been simplified:

   Before

   function App() {
     const [activeId, setActiveId] = useState(null);
   
     return (
       <DndContext
         onDragStart={() => setActiveId('item')}
         onDragEnd={() => setActiveId(null)}
       >
         <Draggable id="item" />
         <DragOverlay>
           {activeId ? <Item id={activeId} /> : null}
         </DragOverlay>
       </DndContext>
     );
   }
   

   Only render the DragOverlay component once per DragDropProvider. The hooks have no effect when used within the overlay.

6. Migrate sortable components

   Update your sortable components using the new useSortable hook:

   Before

   import {useSortable} from '@dnd-kit/sortable';
   
   function SortableItem({id, index}) {
     const {
       attributes,
       listeners,
       setNodeRef,
       transform,
       transition
     } = useSortable({
       id,
       index
     });
   
     return (
       <div
         ref={setNodeRef}
         {...attributes}
         {...listeners}
         style={{
           transform: CSS.Transform.toString(transform),
           transition
         }}
       >
         Item {id}
       </div>
     );
   }
   

   Use the array manipulation helpers from @dnd-kit/helpers to handle reordering.

API reference

A quick lookup for common legacy APIs and their new equivalents, organized by category.

Context & Provider

Legacy (@dnd-kit/core)	New (@dnd-kit/react)
DndContext	DragDropProvider

Events

Legacy	New
active	event.operation.source
over	event.operation.target
active.id	event.operation.source.id
onDragCancel	Check event.canceled inside onDragEnd

Sensors

The legacy MouseSensor and TouchSensor have been merged into a single PointerSensor that handles mouse, touch, and pen input via the native Pointer Events API. You can still apply different behavior per input type by passing a function to activationConstraints and branching on event.pointerType ('mouse', 'touch', or 'pen'):

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

<DragDropProvider
  sensors={(defaults) => [
    ...defaults.filter((sensor) => sensor !== PointerSensor),
    PointerSensor.configure({
      activationConstraints(event, source) {
        if (event.pointerType === 'touch') {
          return [
            new PointerActivationConstraints.Delay({value: 500, tolerance: {x: 5, y: 5}}),
          ];
        }
        return [new PointerActivationConstraints.Distance({value: 8})];
      },
    }),
  ]}
>
  {/* ... */}
</DragDropProvider>

If you don’t configure it, the default already differentiates pointer types — see the PointerSensor docs for the full default behavior.

Legacy (@dnd-kit/core)	New (@dnd-kit/dom)
useSensor / useSensors	Built-in by default. Customize via the sensors prop on DragDropProvider
MouseSensor	PointerSensor from @dnd-kit/dom
TouchSensor	PointerSensor from @dnd-kit/dom
PointerSensor	PointerSensor from @dnd-kit/dom
KeyboardSensor	KeyboardSensor from @dnd-kit/dom

Collision detection

Legacy	New
collisionDetection prop on DndContext	collisionDetector option on useDroppable / useSortable
pointerWithin	pointerIntersection from @dnd-kit/collision
closestCenter	closestCenter from @dnd-kit/collision
closestCorners	closestCorners from @dnd-kit/collision

Modifiers

See the React modifiers guide for usage examples.

Legacy	New
restrictToParentElement	RestrictToElement from @dnd-kit/dom/modifiers
restrictToWindowEdges	RestrictToWindow from @dnd-kit/dom/modifiers
restrictToVerticalAxis	RestrictToVerticalAxis from @dnd-kit/abstract/modifiers
restrictToHorizontalAxis	RestrictToHorizontalAxis from @dnd-kit/abstract/modifiers
createSnapModifier	SnapModifier from @dnd-kit/abstract/modifiers

Sortable

SortableContext is no longer needed. Sortable items register and coordinate with the DragDropProvider automatically when you use useSortable — there’s no wrapping context to configure. Use the type and accept options on useSortable to control which items can be sorted together.

See the sortable state management guide for usage examples.

Legacy	New
SortableContext	No longer needed — see note above
arrayMove	move from @dnd-kit/helpers
verticalListSortingStrategy	Not needed — handled automatically
horizontalListSortingStrategy	Not needed — handled automatically
rectSortingStrategy	Not needed — handled automatically

Next steps

Quickstart guide

Build beautiful drag and drop interfaces in minutes with the new dnd kit

Managing sortable state

Use the move helper from @dnd-kit/helpers or manage state manually

Modifiers

Restrict movement to an element, axis, or snap to a grid in React

Feedback

Configure drag feedback, clone overlays, and drop animations in React