The useDraggable hook requires an id and accepts all the same options as the Draggable class. Refer to the Input section below for more information.

​

API Reference

​

Input

The useDraggable hook accepts the following arguments:

​

Output

The useDraggable hook returns an object containing the following properties:

​

Guides

​

Specifying a drag handle

To specify a drag handle, provide a reference to an element and pass it as the handle argument to the useDraggable hook. Alternatively, you can consume the handleRef ref callback to connect the drag handle element.

import {useDraggable} from '@dnd-kit/react';

function Draggable(props) {
  const {ref, handleRef} = useDraggable({
    id: props.id,
  });

  return (
    <div ref={ref}>
      Draggable
      <button ref={handleRef}>Drag handle</button>
    </div>
  );
}

​

Restricting dragging using modifiers

Use modifiers to modify or restrict the behavior of draggable elements.

Modifiers let you dynamically modify the movement coordinates that are detected by sensors. They can be used for a wide range of use cases, for example:

• Restricting motion to a single axis
• Restricting motion to the draggable node container’s bounding rectangle
• Restricting motion to the draggable node’s scroll container bounding rectangle
• Applying resistance or clamping the motion

Modifiers can be applied globally on the <DragDropProvider> component or locally on individual draggable elements.

Here is an example of how to restrict dragging to the horizontal axis:

import {useDraggable} from '@dnd-kit/react';
import {RestrictToHorizontalAxis} from '@dnd-kit/abstract/modifiers';

function Draggable({id}) {
  const {ref} = useDraggable({
    id,
    modifiers: [RestrictToHorizontalAxis],
  });
}

And here is an example of how to restrict dragging to the container element of the draggable:

import {useDraggable} from '@dnd-kit/react';
import {RestrictToElement} from '@dnd-kit/dom/modifiers';

function Draggable({id}) {
  const {ref} = useDraggable({
    id,
    modifiers: [RestrictToElement.configure({element: document.body})],
  });
}

​

Rendering a drag overlay

You can render a completely different element while the draggable element is being dragged by using the <DragOverlay> component.

import {useDraggable, DragOverlay} from '@dnd-kit/react';

function Draggable() {
  const {ref} = useDraggable({
    id: 'draggable',
  });

  return (
    <>
      <button ref={ref}>
        Draggable
      </button>
      <DragOverlay>
        <div>I will be rendered while dragging...</div>
      </DragOverlay>
    </>
  );
}

The <DragOverlay> component will only render its children when a drag operation is in progress. This can be useful for rendering a completely different element while the draggable element is being dragged.

To get around the fact that the <DragOverlay> component should only rendered once, you can also pass a function as a child to the <DragOverlay> component, which will receive the source as an argument. This can be useful for rendering a clone of the source element while it is being dragged.

import {useDraggable, DragOverlay} from '@dnd-kit/react';

function App(props) {
  return (
    <DragDropProvider>
      <Draggable id="foo" />
      <Draggable id="bar" />
      <DragOverlay>
        {source => (
          <div>
            Dragging {source.id}
          </div>
        )}
      </DragOverlay>
    </DragDropProvider>
  );
}