glodrei/docs/gizmos/drag-controls.mdx

useful add-ons for react-three-fiber

---
title: DragControls
sourcecode: src/web/DragControls.tsx
---

[![storybook](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/gizmos-dragcontrols--drag-controls-story) ![Dom only](https://img.shields.io/badge/-Dom%20only-red)

You can use DragControls to make objects draggable in your scene. It supports locking the drag to specific axes, setting drag limits, and custom drag start, drag, and drag end events.

```tsx
type DragControlsProps = {
  /** If autoTransform is true, automatically apply the local transform on drag, true */
  autoTransform?: boolean
  /** The matrix to control */
  matrix?: THREE.Matrix4
  /** Lock the drag to a specific axis */
  axisLock?: 'x' | 'y' | 'z'
  /** Limits */
  dragLimits?: [[number, number] | undefined, [number, number] | undefined, [number, number] | undefined]
  /** Hover event */
  onHover?: (hovering: boolean) => void
  /** Drag start event */
  onDragStart?: (origin: THREE.Vector3) => void
  /** Drag event */
  onDrag?: (
    localMatrix: THREE.Matrix4,
    deltaLocalMatrix: THREE.Matrix4,
    worldMatrix: THREE.Matrix4,
    deltaWorldMatrix: THREE.Matrix4
  ) => void
  /** Drag end event */
  onDragEnd?: () => void
  children: React.ReactNode
}
```

```jsx
<DragControls>
  <mesh />
</DragControls>
```

You can utilize DragControls as a controlled component by toggling `autoTransform` off, which then requires you to manage the matrix transformation manually. Alternatively, keeping `autoTransform` enabled allows you to apply the matrix to external objects, enabling DragControls to manage objects that are not directly parented within it.

```jsx
const matrix = new THREE.Matrix4()
return (
  <DragControls
    ref={ref}
    matrix={matrix}
    autoTransform={false}
    onDrag={(localMatrix) => matrix.copy(localMatrix)}
```