New to React DnD? Read the overview before jumping into the docs.



What is the @ syntax I see in the ES7 code examples? 

First of all, you don't have to use ES6 or ES7 for React DnD. They make some of the code patterns more succinct, but it's up to you whether to enable these transformations.

When I say “ES7”, I mean ES6 + a few extensions that might make it into ES7 (also known as ES2016). What I mark as the ES7 code in the docs is actually ES6 code + class properties + decorators. You can enable these features by putting { "stage": 0 } into your .babelrc file. You can also enable them individually.

The @ syntax desugars into the simple function calls. You can see that in every example on the website that uses it, such as:

import { DragSource } from 'react-dnd'; @DragSource(type, spec, collect) export default class MyComponent { /* ... */ }

Where do I get the precompiled version? 

If you use npm:

npm install --save react-dnd npm install --save react-dnd-html5-backend

The npm packages default to the CommonJS build. However they also include pre-minified UMD builds in the dist folders. The UMD builds export global window.ReactDnD and window.ReactDnDHTML5Backend respectively.

If you’d rather not use npm, you can use unpkg to access the UMD builds directly: ReactDnD.min.js and ReactDnDHTML5Backend.min.js. You may point your Bower config to them.

How do I test React DnD components and their interaction? 

See the testing tutorial for examples.

How do I make the component draggable only by a small handle? 

Specify the container node as the dragPreview, but only make the drag handle a dragSource(). See the custom drag handle example.

How do I constrain the drag preview movement? 

By default, you can't constrain the drag preview movement because the drag preview is drawn by the browser. You can, however, use a custom drag layer where you're free to rendering anything, with any snapping or constraints.

How do I register a drag source or a drop target when the type depends on props? 

Both DragSource and DropTarget let you pass a function as the first parameter instead of a string or a symbol. If you pass a function, it will be given the current props, and it should return a string, a symbol, or (for drop targets only) an array of either.

How do I combine several drag sources and drop targets in a single component? 

Because DragSource and DropTarget use the partial application, you may compose them using a functional composition helper such as _.flow. In ES7, you can just stack the decorators to achieve the same effect.

Why is the component parameter always null in the beginDrag/endDrag/drop/hover methods? 

When using stateless components, the component parameter will always be null in the beginDrag/endDrag/drop/hover methods. This is because it is not possible to attach a ref to a stateless function component as explained in the React docs.

import { DragSource } from 'react-dnd'; @DragSource(/* ... */) @DropTarget(/* ... */) export default class YourComponent { /* ... */ }

How do I register a drop target for the native files? 

If you are using the HTML5 backend, you can register a drop target for one of the NativeTypes it exports:

import React, { Component } from 'react'; import { NativeTypes } from 'react-dnd-html5-backend'; import { DropTarget } from 'react-dnd'; const fileTarget = { drop(props, monitor) { console.log(monitor.getItem().files); } }; @DropTarget(NativeTypes.FILE, fileTarget, (connect, monitor) => ({ connectDropTarget: connect.dropTarget(), isOver: monitor.isOver(), canDrop: monitor.canDrop() })) export default class FileDropZone extends Component { render() { const { connectDropTarget, isOver, canDrop } = this.props; return connectDropTarget( <div> {!isOver && !canDrop && 'Drag files from the hard drive'} {!isOver && canDrop && 'Drag the files here'} {isOver && 'Drop the files'} </div> ); } }

How do I write a custom backend? 

This is not currently documented, but you can take cues from the HTML5 and Test backend implementations. The backend contract includes setup() and teardown() methods, and connectDragSource(), connectDragPreview() and connectDropTarget() methods that pass the DOM nodes to the backend. Contributions to the documentation are welcome.

I am getting a “Super expression must either be null or a function, not undefined” error 

React DnD requires React 0.13. Make sure you are using at least that version.

Why won't my static methods and properties work? 

Consider this example:

@DragDropContext(HTML5Backend) export default class Page { static willTransitionTo(transition, params) { /* ... */ } render() { /* ... */ } }

It might surprise you that your route handler's willTransitionTo (or a similar method) won't get triggered in this case! React DnD doesn't proxy your components' static methods and properties. This is too fragile and full of edge cases, so you must do it yourself. It's not hard! Just put your statics onto the components returned by React DnD instead:

// You can write your own decorator like this function assignStatics(a) { return b => Object.assign(b, a) } @assignStatics({ willTransitionTo(transition, params) { /* ... */ } }) @DragDropContext(HTML5Backend) export default class Page { render() { /* ... */ } }


Is this Dungeons & Dragons? 

I know, it's only drag and drop, but I like it.

How stable is it? 

Stampsy has been using this library, as well as its non-React predecessor that it was based on, since 2013. It's central to the Stampsy user experience, because all the content is created in a drag and drop post editor that uses React DnD.

What is the roadmap? 

The library is pretty much complete, and there are no new big features planned. Most of the new development now occurs outside React DnD—for example, there is an ongoing work on the touch backend for it.

Who made it and why? 

React DnD was created by Dan Abramov.

Its aim is to expose a powerful API that is browser-agnostic, data-centric, works great with React and Flux, and is testable and extensible. Read The Future of the Drag and Drop API for some context.

It is loosely based on the pre-React code written at Stampsy by Andrew Kuznetsov. Later it received valuable contributions from Alexander Kuznetsov and Nathan Hutchison.

React DnD would not have reached the 1.0 release without the generous donations from:

  • Macropod, a company developing team productivity software;
  • Webflow, a company creating a professional responsive website builder.

Gadzhi Kharkharov styled the website, and the fixed-data-table project provided the website template.

How Do I Contribute? 

Contributing the documentation for the underlying DnD Core library would be a huge help, as it is currently not documented at all, but its concepts leak in some advanced scenarios such as writing tests.

Porting the library to other modern frameworks such as Cycle, Mercury, or Deku, is also appreciated. Such ports would be able to reuse DnD Core logic and the existing backends.

Please let me know via the issue tracker if you create advanced examples such as a Kanban board application, or write a blog post or record a screencast about React DnD, so I can link to it.

While DnD Core is fully tested, React DnD does not currently have any unit tests. Writing them is a great and eagerly desired contribution.