gem-hunter

A simple component for making elements draggable.

[Demo | Changelog]

<Draggable>
  <div>I can now be moved around!</div>
</Draggable>

• Installation
• Compatibility
• Quick Start
• API
  • Draggable
  • DraggableCore
• Using nodeRef
• Controlled vs. Uncontrolled
• Content Security Policy
• Contributing

npm install react-draggable
# or
yarn add react-draggable

// ES Modules
import Draggable from 'react-draggable';
import { DraggableCore } from 'react-draggable';

// CommonJS
const Draggable = require('react-draggable');
const { DraggableCore } = require('react-draggable');

TypeScript types are included.

import React, { useRef } from 'react';
import Draggable from 'react-draggable';

function App() {
  const nodeRef = useRef(null);

  return (
    <Draggable nodeRef={nodeRef}>
      <div ref={nodeRef}>Drag me!</div>
    </Draggable>
  );
}

View the Demo and its source for more examples.

A <Draggable> element wraps an existing element and extends it with new event handlers and styles. It does not create a wrapper element in the DOM.

Draggable items are moved using CSS Transforms. This allows items to be dragged regardless of their current positioning (relative, absolute, or static). Elements can also be moved between drags without incident.

If the item you are dragging already has a CSS Transform applied, it will be overwritten by <Draggable>. Use an intermediate wrapper (<Draggable><span>...</span></Draggable>) in this case.

type DraggableEventHandler = (e: Event, data: DraggableData) => void | false;

type DraggableData = {
  node: HTMLElement,
  x: number, y: number,
  deltaX: number, deltaY: number,
  lastX: number, lastY: number,
};

Note: Setting className, style, or transform on <Draggable> will error. Set them on the child element.

For users that require full control, <DraggableCore> provides drag callbacks without managing state or styles. It does not set any transforms; you must handle positioning yourself.

See React-Resizable and React-Grid-Layout for usage examples.

<DraggableCore> accepts a subset of <Draggable> props:

• allowAnyClick
• allowMobileScroll
• cancel
• disabled
• enableUserSelectHack
• grid
• handle
• nodeRef
• offsetParent
• onDrag
• onMouseDown
• onStart
• onStop
• scale

To avoid ReactDOM.findDOMNode() deprecation warnings in React Strict Mode, pass a nodeRef prop:

function App() {
  const nodeRef = useRef(null);

  return (
    <Draggable nodeRef={nodeRef}>
      <div ref={nodeRef}>Drag me!</div>
    </Draggable>
  );
}

For custom components, forward both the ref and props:

const MyComponent = forwardRef((props, ref) => (
  <div {...props} ref={ref}>Draggable content</div>
));

function App() {
  const nodeRef = useRef(null);

  return (
    <Draggable nodeRef={nodeRef}>
      <MyComponent ref={nodeRef} />
    </Draggable>
  );
}

<Draggable> is a 'batteries-included' component that manages its own state. For complete control, use <DraggableCore>.

For programmatic repositioning while using <Draggable>'s state management, pass the position prop:

function ControlledDraggable() {
  const nodeRef = useRef(null);
  const [position, setPosition] = useState({ x: 0, y: 0 });

  const handleDrag = (e, data) => {
    setPosition({ x: data.x, y: data.y });
  };

  const resetPosition = () => setPosition({ x: 0, y: 0 });

  return (
    <>
      <button onClick={resetPosition}>Reset</button>
      <Draggable nodeRef={nodeRef} position={position} onDrag={handleDrag}>
        <div ref={nodeRef}>Drag me or reset!</div>
      </Draggable>
    </>
  );
}

To prevent text from being highlighted while dragging, react-draggable injects a small <style> element into the document <head> the first time a drag starts (the enableUserSelectHack, on by default). Under a strict Content Security Policy that omits 'unsafe-inline' from style-src, the browser blocks that element and logs a CSP violation.

You have three ways to handle this:

1. Pass a nonce. Provide the same nonce your CSP header advertises and it's applied to the injected element:

   <Draggable nonce={cspNonce}>
     <div>Drag me</div>
   </Draggable>

2. Do nothing, if you use webpack. When no nonce prop is given, react-draggable falls back to webpack's __webpack_nonce__ global if your build defines it — no per-component prop needed.

3. Opt out of the injected style. Set enableUserSelectHack={false} and add the two rules to your own (CSP-compliant) stylesheet:

   .react-draggable-transparent-selection *::-moz-selection { all: inherit; }
   .react-draggable-transparent-selection *::selection { all: inherit; }

The nonce is only read when the element is first created. The same element is shared by every <Draggable>/<DraggableCore> on the page, so set the nonce on whichever instance drags first (or, more simply, set it consistently everywhere).

• Fork the project
• Run yarn dev to start the development server
• Make changes and add tests
• Run yarn test to ensure tests pass
• Submit a PR

1. Update CHANGELOG.md
2. Run make release-patch, make release-minor, or make release-major
3. Run make publish

MIT