Custom Drag Overlays and Multi-Container DnD

DragOverlay renders its content as a React portal, appending it directly to document.body rather than inside the DndContext DOM tree. This means it is never clipped by overflow:hidden or overflow:scroll containers, and it always appears on top of all other elements without requiring manual z-index management.

Because DragOverlay is separate from the original element, it can have visual styles that would break layout if applied to the original. You can add a drop-shadow, a scale transform (make it slightly larger than the original), or a rotation effect. These visual cues communicate to the user that the item is "lifted" and in motion.

DragOverlay needs to know what to render. Track the active drag ID in state: set it in onDragStart with event.active.id and clear it in onDragEnd with null. Inside DragOverlay, use that ID to find the corresponding item data and render the correct preview component.

When using DragOverlay, the original draggable item should become a visual placeholder while dragging. If using useSortable, apply opacity: 0 or a dashed border when isDragging is true. This shows the "slot" the item will return to if the drag is cancelled and the gap it leaves when moving to a new position.

Multi-container drag and drop means items can be dragged between two or more separate lists. The setup requires a single DndContext wrapping all containers, with each container having its own SortableContext. All item IDs across all containers must be globally unique to prevent collisions.

For smooth cross-container animation, update state in onDragOver rather than waiting for onDragEnd. When the dragged item crosses into a new container, move it from the source container to the target container immediately. This gives real-time visual feedback of where the item will land.

When dragging across multiple SortableContext instances, all item IDs must be unique across the entire DndContext — not just within each list. If two containers share an ID, dnd-kit cannot determine which item is active. Use UUIDs or prefix IDs with the container name to ensure global uniqueness.

useDraggable and useSortable accept a data option: useSortable({ id, data: { containerId, type } }). This data is available in drag event callbacks as event.active.data.current. In multi-container scenarios, you can store the source container ID in data and use it in onDragOver to know where the item is coming from.

Multi-container state typically uses an object keyed by container ID, each containing an array of items. In onDragOver, when the active item is in a different container than the over target, remove the item from the source container array and insert it into the target container array at the correct position.

The KeyboardSensor works for multi-container DnD. Users press Arrow keys to move between items within a container, and when they reach the edge of a container, they can continue to cross into adjacent containers. The SortableContext collisionDetection algorithm determines the nearest valid drop target based on position.

DndContext accepts a collisionDetection prop that determines how it calculates which droppable the dragged item is over. The default closestCenter works well for most lists. closestCorners is better for grids. pointerWithin only activates a droppable when the cursor is physically inside it.

Where does DragOverlay render its content in the DOM?

DragOverlay renders as a portal to document.body, providing visual independence from layout constraints. Track activeDragId in onDragStart/onDragEnd to render the correct overlay content. Multi-container DnD uses multiple SortableContext instances inside one DndContext with globally unique IDs. Update state in onDragOver for smooth cross-container animations, using event.active.data.current for source container metadata.