react-dnd

What is react-dnd?

The react-dnd package is a set of React utilities to help you build complex drag and drop interfaces while keeping your components decoupled. It provides a way to use drag and drop features in React by turning any React component into a draggable or a droppable area.

What are react-dnd's main functionalities?

Draggable Components

This feature allows you to turn any component into a draggable item. The useDrag hook is used to make components draggable and to monitor their state.

{"import { useDrag } from 'react-dnd';\n\nfunction DraggableComponent() {\n  const [{isDragging}, dragRef] = useDrag({\n    type: 'BOX',\n    collect: monitor => ({\n      isDragging: !!monitor.isDragging(),\n    }),\n  });\n\n  return (\n    <div ref={dragRef} style={{ opacity: isDragging ? 0.5 : 1 }}>\n      Drag Me\n    </div>\n  );\n}"}

Droppable Areas

This feature allows you to define areas where draggable items can be dropped. The useDrop hook is used to handle the drop events and to determine the state of the drop targets.

{"import { useDrop } from 'react-dnd';\n\nfunction DroppableComponent() {\n  const [{canDrop, isOver}, dropRef] = useDrop({\n    accept: 'BOX',\n    drop: () => ({ name: 'DroppableComponent' }),\n    collect: monitor => ({\n      isOver: monitor.isOver(),\n      canDrop: monitor.canDrop(),\n    }),\n  });\n\n  return (\n    <div ref={dropRef} style={{ backgroundColor: isOver ? 'green' : 'white' }}>\n      {canDrop ? 'Release to drop' : 'Drag a box here'}\n    </div>\n  );\n}"}

Custom Drag Layer

This feature allows you to create a custom drag layer that can be used to display a custom preview of the draggable item. The useDragLayer hook provides information about the item being dragged and its position.

{"import { useDragLayer } from 'react-dnd';\n\nfunction CustomDragLayer() {\n  const { isDragging, item, currentOffset } = useDragLayer((monitor) => ({\n    item: monitor.getItem(),\n    currentOffset: monitor.getSourceClientOffset(),\n    isDragging: monitor.isDragging(),\n  }));\n\n  if (!isDragging) {\n    return null;\n  }\n\n  return (\n    <div style={{ position: 'fixed', pointerEvents: 'none', left: currentOffset.x, top: currentOffset.y }}>\n      {/* Render custom drag layer here */}\n    </div>\n  );\n}"}

Other packages similar to react-dnd

react-beautiful-dnd

react-beautiful-dnd is a higher-level abstraction built on top of the lower-level primitives provided by react-dnd. It offers a more opinionated but simpler API and focuses on vertical and horizontal lists. It provides beautiful and accessible drag and drop for lists with React.

react-sortable-hoc

react-sortable-hoc is a set of higher-order components to turn any list into an animated, touch-friendly, sortable list. It's more focused on list sorting capabilities and less on general drag and drop scenarios compared to react-dnd.

dnd-kit

dnd-kit is a modern drag and drop toolkit for React that is designed to be more performant and flexible than react-dnd. It provides hooks and utilities to build complex drag and drop interfaces and supports multiple backends, including touch and keyboard.

README

React DnD

Drag and drop for React with full DOM control.

Currently works on top of HTML5 drag-and-drop API, but is moving towards a swappable implementation. Support for touch events is on the roadmap but not currently implemented.

If your company uses React DnD and would like to speed up its development, consider sponsoring the project. I'm currently doing it in the spare time but I would be happy to work on it part-time. Drop me an email at [e-mail]. Exciting new features take time.

Philosophy

• Keep user in full control over rendering;
• Don't make assumptions about consuming components and their structure;
• Hide underlying implementation and its quirks;
• Make 80% easy, 20% possible.

Live Demo

See it in action! (Source)

Demo contains a variety of things you can implement with this library, including:

• Reacting to hover and dropping;
• Dropping files;
• Dragging a box around with snapping;
• Drawing a custom drag layer;
• Making cards sortable.

You can do much more, but these examples will help you get started!

Features

• Emits zero DOM or CSS of its own;
• Like original HTML5 API, emphasizes dragging data and not just “draggable views”;
• Support dropping files using the same API;
• Lets components register as “drag sources” or “drop targets” for different kinds of data;
• Lets a single component contain several drag sources and drop targets;
• Lets you provide a custom drag handle, whether DOM subnode or an image;
• Takes the best from HTML5 API but hides its many quirks:
  • doesn't require you to preventDefault anything to start working;
  • emits enter and leave as you'd expect instead of doing it for every child node;
  • lets you read drag state from render();
  • consistently fires events even if source DOM node was removed;
• Includes a helper to preload images for drag thumbnails;
• Lets you render a custom drag layer if you'd rather draw your own drag preview.

Documentation

SemVer

We plan to follow SemVer after 1.0. Before 1.0, minor version bumps may contain breaking changes. Breaking changes will be documented in the Upgrade Guide.

API Reference

Complete API reference is available here.

Walkthrough

If you don't feel comfortable diving into examples source code just yet, you can start with the walkthrough.

Examples

Have you played with live demo yet? Here's the source code for it.

To try it locally, clone the project and run:

npm install
npm start
open http://localhost:8080/

Examples use ES6 syntax via Babel transpiler. You can still use React DnD in an ES5 codebase, but if you copy code from examples, make sure you translate it to ES5 where needed.

Installation

The library can be used separately (dist/ReactDND.min.js) or with a bundler such as Webpack or Browserify.

npm install --save react-dnd

Future Roadmap

• Touch support;
• Support for mouse events instead of HTML5 drag-and-drop events;
• Dragging multiple items at once.

Production Usage

• Stampsy, where it was originally developed, is using React DnD for the post editor.
• Add your company!

See Also

• react-draggable by Matt Zabriskie
• react-sortable by Daniel Stocks
• react-dropzone by Param Aggarwal

Thanks

This library is a React port of an API, parts of which were originally written by Andrew Kuznetsov.

A lot of recent progress is due to Nathan Hutchison's contributions and effort.

Changelog

1.0.0-alpha (2015-04-20)

• 1.0.0-alpha (701ff6a)
• Add a todo (09f1a39)
• Add comment (e673826)
• Add enter/leave tracking for dragging files or links out of window (60cffe9)
• Add image drag preview example (0ef96a1)
• Add in-progress drag handle example (36df14b)
• Add less verbose single handler API (b29eae2)
• Add nested example (1129ca7)
• Add nesting sources example (c0209ea)
• Add observe draft (7f8f5e8)
• Add sortable (3764e2b)
• Add sortable stress test (fd700f6)
• add todo (48ed284)
• Add use strict for linter (258206f)
• amend TODO (22f6feb)
• bikeshed (f37f5b7)
• Bump Babel (ead1345)
• Bust cache (32f7811)
• Change API to a less verbose one (5bab482)
• Change API to accept two functions (305686b)
• Complex hover handling with drop targets changing under cursor (3215e89)
• Convert another example (553695a)
• Decorators all the way (b63a29d)
• Disable all but the simplest example (f1afb03)
• Don't export backend by default (a0ab900)
• Don't pass actual props (a87131c)
• Don't use React internal modules (47a34f7)
• edge (8b642ee)
• ES6 all the way (c861472)
• Extract module (03dcdde)
• Fix (15ba58d)
• Fix an edge case when a file is dropped outside <body> (0b23fe3)
• Fix disposal (1a645a4)
• Fix examples, make perf opt-in (8dfa342)
• Fix IE (a384bb8)
• Fix linting with latest ESLint (83fff54)
• Fix native beginDrag call (c34cf3f)
• Fix sortable on Firefox (02c5527)
• Fixes for conflicting HTML5 backends (ddc3e52)
• HOC might be a better fit after all (f8a5610)
• Improve perf (c41ba87)
• initial attempt at having the first example use dnd-core (57d65cc)
• Initial drag image offset implementation (77beee4)
• Initial support for native item types (c27c1e2)
• It sort of works, but not the right way (21715c9)
• It works (4658cb1)
• Make anchors truly customizable (b11f2cf)
• Make cards have limited width (3e89883)
• Make it look more fashionable (9228f86)
• Memoize to fix perf (f96f772)
• Minor (b1eb175)
• More nasty example (f39d0eb)
• Move code around (d5570ea)
• Move connect to the top (b6eace8)
• Move some stuff around (d0a2cb7)
• Move utils to separate files (8bb1277)
• Naming (76f5576)
• Pass component as last parameter to allow DOM access for methods where it is safe (4ff7a1c)
• Playing around with higher-order API (9ffb6b7)
• Port dustbin-interesting (403834a)
• Prevent animating an item back to incorrect position if its rect changed (a72a01b)
• Proof of concept of decorator API (84b0ec4)
• Proof of concept of observe polyfill (1db3dd5)
• Push disposables out of the backend (1f74ac8)
• React is external when minifying (ddca3ae)
• Rebuild dist (37ffa80)
• Rebuild dist (ef35926)
• Rebuild dist (1ad2e11)
• Rebuild dist (8709ca7)
• Rebuild dist (efcff3d)
• Rebuild dist with a fix (f480730)
• Refactor and improve perf 10x (3a6cd7f)
• Remove all code lol (bbd342c)
• Remove classic function API, use decorator desugaring instead (43c4aa3)
• Remove React dependency from HTML5 backend (4ca94f2)
• Rename inject => collect (a1489a6)
• Reset hover when drag ends (460377f)
• Separate stress test example (ae1f4be)
• Simpler connect API (fbabc65)
• Simplify API by passing props (75dc904)
• simplify example (8bcdb95)
• Simplify the code with beginDrag(array) (16cd843)
• Slightly better guards (4d00c2e)
• Sortable. Work in progress (3517eb1)
• Start by removing all examples except the simplest one (8c41048)
• Start work on drag around naive (dbdeb3f)
• Support custom drag layer (f6feb37)
• Support custom drag previews (ca3ac0e)
• Support custom drop effects (7956b21)
• Support naive coordinate tracking (030a825)
• Support source DOM node being removed from DOM (6da684c)
• This is getting seriously fun (de7c27f)
• todo (30ec27a)
• Tweak manager key API (cb3e02b)
• Unsubscribe on unmounting (ef68100)
• Update API (027a6bb)
• Update Babel (47908c6)
• Update coordinate code (66947a6)
• Update dist (76ef9fc)
• Update dnd-core and misc (d878e39)
• Update examples to new proposed API (00862fd)
• update the dragState to show drop hint (911e1e6)
• Update to React 0.13 (9f2598e)
• update TODO (f689cdf)
• update TODO (25e4f0f)
• update TODO (3fbb63e)
• Update todo (b2c112b)
• Use disposables for cleaner contract, temporarily depend on rx-lite (725b01b)
• Use disposables instead of rx-lite (82f59ba)
• Use ES6 classes in example (c2d8b0a)
• Use hover() for sortable (d2dbf37)
• Use just shallowEqual for state (ee6d51b)
• Use rAF for performance (d1b68b0)
• Use shallowEqualScalar by default (28242c4)
• Whitespace (4c9e344)
• Whoops (38b1933)
• work in progress (3d2d4fe)
• Working HOC proof of concept (8f42428)