0
# React Draggable
1

2
React Draggable is a React component library that provides drag-and-drop functionality for React applications. It offers two main components: Draggable (a stateful wrapper that manages position) and DraggableCore (a stateless component for full control over drag behavior). The library supports advanced features including axis constraints, boundary restrictions, grid snapping, custom handles, touch support, and CSS transform-based positioning for optimal performance.
3

4
## Package Information
5

6
- **Package Name**: react-draggable
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow types
9
- **Installation**: `npm install react-draggable`
10
- **Peer Dependencies**: React >=16.3.0, ReactDOM >=16.3.0
11

12
## Core Imports
13

14
```javascript
15
// Default import (Draggable component)
16
import Draggable from 'react-draggable';
17

18
// Named import (DraggableCore component)
19
import { DraggableCore } from 'react-draggable';
20

21
// Both components together
22
import Draggable, { DraggableCore } from 'react-draggable';
23
```
24

25
CommonJS:
26

27
```javascript
28
// Default require
29
const Draggable = require('react-draggable');
30
const DraggableCore = Draggable.DraggableCore;
31

32
// Destructured require  
33
const { default: Draggable, DraggableCore } = require('react-draggable');
34
```
35

36
## Basic Usage
37

38
```javascript
39
import React from 'react';
40
import Draggable from 'react-draggable';
41

42
function App() {
43
  return (
44
    <Draggable>
45
      <div style={{ padding: '20px', background: '#f0f0f0' }}>
46
        Drag me around!
47
      </div>
48
    </Draggable>
49
  );
50
}
51

52
// With event handlers and position control
53
function ControlledDraggable() {
54
  const [position, setPosition] = React.useState({ x: 0, y: 0 });
55

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

60
  return (
61
    <Draggable position={position} onDrag={handleDrag}>
62
      <div>Controlled draggable element</div>
63
    </Draggable>
64
  );
65
}
66
```
67

68
## Architecture
69

70
React Draggable is built around several key concepts:
71

72
- **CSS Transform-based**: Uses CSS transforms instead of changing position properties for better performance
73
- **Controlled/Uncontrolled**: Supports both controlled (with position prop) and uncontrolled (internal state) usage patterns
74
- **Event-driven**: Rich event system with detailed position and delta information
75
- **Touch Support**: Full touch device support with configurable mobile scroll behavior
76
- **Boundary System**: Flexible boundary constraints using parent elements, selectors, or pixel values
77
- **Performance Optimized**: Minimal DOM manipulation with efficient transform-based positioning
78

79
## Core Types
80

81
```typescript { .api }
82
interface ControlPosition {
83
  x: number;
84
  y: number;
85
}
86

87
interface PositionOffsetControlPosition {
88
  x: number | string;
89
  y: number | string;
90
}
91

92
interface DraggableData {
93
  node: HTMLElement;
94
  x: number;
95
  y: number;
96
  deltaX: number;
97
  deltaY: number;
98
  lastX: number;
99
  lastY: number;
100
}
101

102
interface DraggableBounds {
103
  left?: number;
104
  right?: number;
105
  top?: number;
106
  bottom?: number;
107
}
108

109
type DraggableEvent = React.MouseEvent<HTMLElement | SVGElement>
110
  | React.TouchEvent<HTMLElement | SVGElement>
111
  | MouseEvent
112
  | TouchEvent;
113

114
type DraggableEventHandler = (
115
  e: DraggableEvent,
116
  data: DraggableData
117
) => void | false;
118
```
119

120
## Capabilities
121

122
### Draggable Component
123

124
The main Draggable component provides a stateful draggable wrapper that manages its own position and applies CSS transforms to move elements smoothly.
125

126
```typescript { .api }
127
interface DraggableProps {
128
  // Position management
129
  axis?: 'both' | 'x' | 'y' | 'none'; // default: 'both'
130
  defaultPosition?: ControlPosition; // default: {x: 0, y: 0}
131
  position?: ControlPosition;
132
  positionOffset?: PositionOffsetControlPosition;
133
  
134
  // Boundaries and constraints
135
  bounds?: DraggableBounds | string | false; // default: false
136
  grid?: [number, number];
137
  scale?: number; // default: 1
138
  
139
  // Interaction controls
140
  handle?: string;
141
  cancel?: string;
142
  disabled?: boolean; // default: false
143
  
144
  // Event handlers
145
  onStart?: DraggableEventHandler; // default: () => {}
146
  onDrag?: DraggableEventHandler; // default: () => {}
147
  onStop?: DraggableEventHandler; // default: () => {}
148
  onMouseDown?: (e: MouseEvent) => void; // default: () => {}
149
  
150
  // Styling
151
  defaultClassName?: string; // default: 'react-draggable'
152
  defaultClassNameDragging?: string; // default: 'react-draggable-dragging'
153
  defaultClassNameDragged?: string; // default: 'react-draggable-dragged'
154
  
155
  // Advanced options
156
  allowAnyClick?: boolean; // default: false
157
  allowMobileScroll?: boolean; // default: false
158
  enableUserSelectHack?: boolean; // default: true
159
  offsetParent?: HTMLElement;
160
  nodeRef?: React.RefObject<HTMLElement>;
161
  
162
  // Required
163
  children: React.ReactNode;
164
}
165
```
166

167
[Draggable Component](./draggable.md)
168

169
### DraggableCore Component
170

171
The low-level DraggableCore component provides drag events without position management, giving full control over drag behavior and positioning to the parent component.
172

173
```typescript { .api }
174
interface DraggableCoreProps {
175
  // Interaction controls
176
  handle?: string;
177
  cancel?: string;
178
  disabled?: boolean; // default: false
179
  
180
  // Event handlers
181
  onStart?: DraggableEventHandler; // default: () => {}
182
  onDrag?: DraggableEventHandler; // default: () => {}
183
  onStop?: DraggableEventHandler; // default: () => {}
184
  onMouseDown?: (e: MouseEvent) => void; // default: () => {}
185
  
186
  // Advanced options
187
  allowAnyClick?: boolean; // default: false
188
  allowMobileScroll?: boolean; // default: false
189
  enableUserSelectHack?: boolean; // default: true
190
  offsetParent?: HTMLElement;
191
  grid?: [number, number];
192
  scale?: number; // default: 1
193
  nodeRef?: React.RefObject<HTMLElement>;
194
  
195
  // Required
196
  children: React.ReactNode;
197
}
198
```
199

200
[DraggableCore Component](./draggable-core.md)