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

FAQ

Usage

Where do I get the precompiled version?

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. With decorators, 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 function components, refs cannot normally be attached. However, if you use React.forwardRef, then you can access the rendered component. If your component exposes an imperative API via the useImperativeHandle hook, then you can expose functionality that way.

If you use a tool like babel-react-optimize preset or babel-plugin-transform-react-pure-class-to-function, then be aware that your class definition may implicitly be transformed into a function component, which may result in a null argument.

import { DragSource } from 'react-dnd'
import flow from 'lodash/flow'

class YourComponent {
  /* ... */
}

export default flow(
  DragSource(/* ... */),
  DropTarget(/* ... */),
)(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 from 'react'
import { NativeTypes } from 'react-dnd-html5-backend'
import { DropTarget } from 'react-dnd'

const fileTarget = {
  drop(props, monitor) {
    console.log(monitor.getItem().files)
  },
}

function FileDropZone({ connectDropTarget, isOver, canDrop }) {
  return connectDropTarget(
    <div>
      {!isOver && !canDrop && 'Drag files from the hard drive'}
      {!isOver && canDrop && 'Drag the files here'}
      {isOver && 'Drop the files'}
    </div>,
  )
}

export default DropTarget(NativeTypes.FILE, fileTarget, (connect, monitor) => ({
  connectDropTarget: connect.dropTarget(),
  isOver: monitor.isOver(),
  canDrop: monitor.canDrop(),
}))(FileDropZone)

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:

class Page {
  static willTransitionTo(transition, params) {
    /* ... */
  }

  render() {
    /* ... */
  }
}

export default DragDropContext(HTML5Backend)(Page)

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:

class Page {
  render() {
    /* ... */
  }
}

Page = DragDropContext(HTML5Backend)(Page)
Page.willTransitionTo = function(transition, params) {
  /* ... */
}

export default Page

Meta

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.