Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DndProvider
✓ import { DndProvider } from 'react-dnd'
✗ const { DndProvider } = require('react-dnd')
React DnD is ESM-only since v16.0.0. CommonJS `require` syntax will result in an error in Node.js environments.
useDrag
✓ import { useDrag } from 'react-dnd'
✗ import useDrag from 'react-dnd'
This is a named export and must be destructured. Attempting a default import will fail.
useDrop
✓ import { useDrop } from 'react-dnd'
✗ import { useDrop, DropTargetMonitor } from 'react-dnd/lib/hooks'
Hooks are directly exported from the main 'react-dnd' package since v14; older versions might have had different import paths.
HTML5Backend
✓ import { HTML5Backend } from 'react-dnd-html5-backend'
✗ import { HTML5Backend } from 'react-dnd'
Backends are provided as separate packages and must be imported from their specific package, not the main 'react-dnd' package.
This quickstart demonstrates how to create a simple draggable box and a drop target using the `useDrag` and `useDrop` hooks within a `DndProvider`.
import { DndProvider, useDrag, useDrop } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';
import React, { useState } from 'react';
import ReactDOM from 'react-dom/client';
// Define item types for drag and drop
const ItemTypes = {
BOX: 'box',
};
// Draggable component
const DraggableBox: React.FC<{ name: string }> = ({ name }) => {
const [{ isDragging }, drag] = useDrag(() => ({
type: ItemTypes.BOX,
item: { name },
collect: (monitor) => ({
isDragging: monitor.isDragging(),
}),
}));
return (
<div
ref={drag}
style={{
opacity: isDragging ? 0.5 : 1,
cursor: 'move',
padding: '8px',
border: '1px dashed gray',
backgroundColor: 'white',
marginBottom: '4px',
}}
>
{name}
</div>
);
};
// Drop target component
const DropTargetBox: React.FC = () => {
const [droppedItems, setDroppedItems] = useState<string[]>([]);
const [{ isOver }, drop] = useDrop(() => ({
accept: ItemTypes.BOX,
drop: (item: { name: string }) => {
setDroppedItems((prev) => [...prev, item.name]);
},
collect: (monitor) => ({
isOver: monitor.isOver(),
}),
}));
const backgroundColor = isOver ? 'lightgreen' : '#eee';
return (
<div
ref={drop}
style={{
minHeight: '100px',
border: '1px solid black',
backgroundColor,
padding: '16px',
marginTop: '16px',
}}
>
{isOver ? 'Release to drop' : 'Drag items here'}
{droppedItems.length > 0 && (
<ul>
{droppedItems.map((item, index) => (
<li key={index}>{item}</li>
))}
</ul>
)}
</div>
);
};
// Main application component
const App: React.FC = () => {
return (
<DndProvider backend={HTML5Backend}>
<div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
<h1>React DnD Example</h1>
<p>Drag the boxes below into the drop target.</p>
<DraggableBox name="Item A" />
<DraggableBox name="Item B" />
<DropTargetBox />
</div>
</DndProvider>
);
};
const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<App />);
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module C:\path\to\node_modules\react-dnd\dist\index.mjs not supported.
Attempting to import `react-dnd` using CommonJS `require()` syntax in a Node.js or older bundler environment after upgrading to v16.0.0 or later.
fixUpdate your code to use ES module `import` syntax (`import { DndProvider } from 'react-dnd'`). For Node.js projects, ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for files that import `react-dnd`. TypeError: Cannot read properties of undefined (reading 'DragSource')
Attempting to use the deprecated Decorators API (e.g., `@DragSource`, `@DropTarget`) in versions 15.0.0 or later, where these exports have been removed.
fixRefactor your component to use the Hooks API (`useDrag`, `useDrop`, `useDragLayer`). Refer to the official React DnD documentation for migration guides from the Decorators API to the Hooks API.
Invariant Violation: Could not find the DndContext. Either render your component as a child of <DndProvider>...
A component attempting to use `useDrag`, `useDrop`, or `useDragLayer` hooks is not rendered within a `DndProvider` component.
fixWrap your root component or the relevant section of your application with `<DndProvider backend={HTML5Backend}>` (or another backend) to provide the necessary context for the hooks. Audit
Dependencies
reactrequiredCore React library required for UI components and hooks
@types/reactrequiredTypeScript type definitions for React, essential for type-safe development
@types/nodeoptionalTypeScript type definitions for Node.js, sometimes required for build tools or specific backend implementations
@types/hoist-non-react-staticsoptionalTypeScript types for an internal utility, though less critical with the deprecation of decorator API