You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/docsite/markdown/docs/00 Quick Start/Overview.md
+22-118
Original file line number
Diff line number
Diff line change
@@ -10,16 +10,6 @@ React DnD is unlike most of the drag and drop libraries out there, and it can be
10
10
Some of these concepts resemble the [Flux](http://facebook.github.io/flux/) and [Redux](https://github.com/reactjs/react-redux) architectures.
11
11
This is not a coincidence, as React DnD uses Redux internally.
12
12
13
-
### Backends
14
-
15
-
React DnD is built on top of the [HTML5 drag and drop API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_and_drop). It is a reasonable default because it screenshots the dragged DOM node and uses it as a “drag preview” out of the box. It's handy that you don't have to do any drawing as the cursor moves. This API is also the only way to handle the file drop events.
16
-
17
-
Unfortunately, the HTML5 drag and drop API also has some downsides. It does not work on touch screens, and it provides less customization opportunities on IE than in other browsers.
18
-
19
-
This is why **the HTML5 drag and drop support is implemented in a pluggable way** in React DnD. You don't have to use it. You can write a different implementation, based on touch events, mouse events, or something else entirely. Such pluggable implementations are called the _backends_ in React DnD. Only the [HTML5 backend](/docs/backends/html5) comes with the library, but more may be added in the future.
20
-
21
-
The backends perform a similar role to that of React's synthetic event system: **they abstract away the browser differences and process the native DOM events.** Despite the similarities, React DnD backends do not have a dependency on React or its synthetic event system. Under the hood, all the backends do is translate the DOM events into the internal Redux actions that React DnD can process.
22
-
23
13
### Items and Types
24
14
25
15
Like Flux (or Redux), React DnD uses data, and not the views, as the source of truth. When you drag something across the screen, we don't say that a component, or a DOM node is being dragged. Instead, we say that an _item_ of a certain _type_ is being dragged.
@@ -97,129 +87,43 @@ Whenever you want to make a component or some part of it draggable, you need to
97
87
98
88
The _drop targets_ are very similar to the drag sources. The only difference is that a single drop target may register for several item types at once, and instead of producing an item, it may handle its hover or drop.
99
89
100
-
### Higher-Order Components and Decorators
101
-
102
-
How do you wrap your components? What does wrapping even mean? If you have not worked with higher-order components before, go ahead and read [this article](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750), as it explains the concept in detail.
103
-
104
-
**A higher-order component is a function that takes a React component class, and returns another React component class.** The wrapping component provided by the library renders _your_ component in its `render` method and forwards the props to it, but also adds some useful behavior.
105
-
106
-
In React DnD, [`DragSource`](/docs/api/drag-source) and [`DropTarget`](/docs/api/drop-target), as well as a few other top-level exported functions, are in fact higher-order components. They breathe the drag and drop magic into your components.
107
-
108
-
One caveat of using them is that they require _two_ function applications. For example, here's how to wrap `YourComponent` in a [`DragSource`](/docs/api/drag-source):
109
-
110
-
```jsx
111
-
import { DragSource } from'react-dnd'
112
-
113
-
classYourComponent {
114
-
/* ... */
115
-
}
116
-
117
-
exportdefaultDragSource(/* ... */)(YourComponent)
118
-
```
90
+
### Backends
119
91
120
-
Notice how, after specifying the [`DragSource`](/docs/api/drag-source) parameters in the first function call, there is a _second_ function call, where you finally pass your class. This is called [currying](http://en.wikipedia.org/wiki/Currying), or [partial application](http://en.wikipedia.org/wiki/Partial_application), and is necessary for the [decorator syntax](http://github.com/wycats/javascript-decorators) to work out of the box:
92
+
React DnD uses the [HTML5 drag and drop API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Drag_and_drop). It is a reasonable default because it screenshots the dragged DOM node and uses it as a “drag preview” out of the box. It's handy that you don't have to do any drawing as the cursor moves. This API is also the only way to handle the file drop events.
121
93
122
-
```jsx
123
-
import { DragSource } from'react-dnd'
94
+
Unfortunately, the HTML5 drag and drop API also has some downsides. It does not work on touch screens, and it provides less customization opportunities on IE than in other browsers.
124
95
125
-
@DragSource(/* ... */)
126
-
exportdefaultclassYourComponent {
127
-
/* ... */
128
-
}
129
-
```
96
+
This is why **the HTML5 drag and drop support is implemented in a pluggable way** in React DnD. You don't have to use it. You can write a different implementation, based on touch events, mouse events, or something else entirely. Such pluggable implementations are called the _backends_ in React DnD.
130
97
131
-
You don't have to use this syntax, but if you like it, you can enable it by transpiling your code with [Babel](http://babeljs.io), and putting `{ "stage": 1 }` into your [.babelrc file](https://babeljs.io/docs/usage/babelrc/).
98
+
The library currently ships with the [HTML backend](docs/backends/html5), which should be sufficient for most web applications. There is also a [Touch backend](/docs/backend/touch) that can be used for mobile web applications.
132
99
133
-
Even if you don't plan to use decorators, the partial application can still be handy, because you can combine several [`DragSource`](/docs/api/drag-source) and [`DropTarget`](/docs/api/drop-target) declarations in JavaScript using a functional composition helper such as [`_.flow`](https://lodash.com/docs#flow). With decorators, you can stack the decorators to achieve the same effect.
100
+
The backends perform a similar role to that of React's synthetic event system: **they abstract away the browser differences and process the native DOM events.** Despite the similarities, React DnD backends do not have a dependency on React or its synthetic event system. Under the hood, all the backends do is translate the DOM events into the internal Redux actions that React DnD can process.
Now you should have an understanding of the various moving pieces of React DnD:
151
105
152
-
### Putting It All Together
106
+
- Item objects and types
107
+
- DnD state via flux
108
+
- Monitors for observing DnD state
109
+
- Collector functions for turning monitor output into consumable props
110
+
- Connectors for attaching the DnD state machine to view nodes (e.g. DOM elements)
153
111
154
-
Below is an example of wrapping an existing `Card` component into a drag source.
112
+
Now let's talk about how these pieces come together in your components. You have two options: a modern hooks-based API and the classic Decorators-based API.
155
113
156
-
```jsx
157
-
importReactfrom'react'
158
-
import { DragSource } from'react-dnd'
159
-
160
-
// Drag sources and drop targets only interact
161
-
// if they have the same string type.
162
-
// You want to keep types in a separate file with
163
-
// the rest of your app's constants.
164
-
constTypes= {
165
-
CARD:'card'
166
-
}
114
+
### Hooks
167
115
168
-
/**
169
-
* Specifies the drag source contract.
170
-
* Only `beginDrag` function is required.
171
-
*/
172
-
constcardSource= {
173
-
beginDrag(props) {
174
-
// Return the data describing the dragged item
175
-
constitem= { id:props.id }
176
-
return item
177
-
},
178
-
179
-
endDrag(props, monitor, component) {
180
-
if (!monitor.didDrop()) {
181
-
return
182
-
}
183
-
184
-
// When dropped on a compatible target, do something
Modern React applications have replaced the Higher-Order-Component pattern with hooks. Hooks are a feature of React, introduced in 16.8, that allow for developers to write stateful function components. They also fantastic for managing stateful components, and also for interacting with external stateful systems (\***cough**\* like a Drag-and-Drop engine \***cough**\*).
190
117
191
-
/**
192
-
* Specifies which props to inject into your component.
193
-
*/
194
-
functioncollect(connect, monitor) {
195
-
return {
196
-
// Call this function inside render()
197
-
// to let React DnD handle the drag events:
198
-
connectDragSource:connect.dragSource(),
199
-
// You can ask the monitor about the current drag state:
200
-
isDragging:monitor.isDragging()
201
-
}
202
-
}
118
+
If you are unfamiliar with React hooks, refer to the React blog post, [Introducing Hooks](https://reactjs.org/docs/hooks-intro.html).
203
119
204
-
functionCard(props) {
205
-
// Your component receives its own props as usual
206
-
const { id } = props
120
+
React-DnD provides hooks that connect your components to the DnD engine, and allow you to collect monitor state for rendering.
207
121
208
-
// These two props are injected by React DnD,
209
-
// as defined by your `collect` function above:
210
-
const { isDragging, connectDragSource } = props
122
+
For an overview of the hooks-based API, refer to the [Hooks Overview](/docs/api/hooks-overview) page.
Now you know enough about React DnD to explore the rest of the documentation!
225
-
The [tutorial](/docs/tutorial) is a great place to start.
129
+
The [hooks overview](/docs/api/hooks-overview) and [decorators overview](/docs/api/decorators-overview) documentation pages are great places to start. Or jump straight into the [tutorial app](/docs/tutorial) and build a chess game!
Copy file name to clipboardExpand all lines: packages/docsite/markdown/docs/02 Monitoring State/DragLayerMonitor.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ _New to React DnD? [Read the overview](/docs/overview) before jumping into the d
7
7
8
8
# DragLayerMonitor
9
9
10
-
`DragLayerMonitor` is an object passed to a collecting function of the [`DragLayer`](/docs/api/drag-layer). Its methods let you get information about the global drag state.
10
+
`DragLayerMonitor` is an object passed to a collecting function of a [hooks-based](/docs/api/use-drag-layer) or [decorator-based](/docs/api/drag-layer) drag layer. Its methods let you get information about the global drag state.
Copy file name to clipboardExpand all lines: packages/docsite/markdown/docs/02 Monitoring State/DragSourceMonitor.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ _New to React DnD? [Read the overview](/docs/overview) before jumping into the d
7
7
8
8
# DragSourceMonitor
9
9
10
-
`DragSourceMonitor` is an object passed to a collecting function of the [`DragSource`](/docs/api/drag-source). Its methods let you get information about the drag state of a specific drag source. The specific drag source bound to that monitor is called the monitor's _owner_ below.
10
+
`DragSourceMonitor` is an object passed to a collecting function of a [hooks-based](/docs/api/use-drag) or [decorator-based](/docs/api/drag-source) dragging source. Its methods let you get information about the drag state of a specific drag source. The specific drag source bound to that monitor is called the monitor's _owner_ below.
Copy file name to clipboardExpand all lines: packages/docsite/markdown/docs/02 Monitoring State/DropTargetMonitor.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ _New to React DnD? [Read the overview](/docs/overview) before jumping into the d
7
7
8
8
# DropTargetMonitor
9
9
10
-
`DropTargetMonitor` is an object passed to a collecting function of the [`DropTarget`](/docs/api/drop-target). Its methods let you get information about the drag state of a specific drop target. The specific drop target bound to that monitor is called the monitor's _owner_ below.
10
+
`DropTargetMonitor` is an object passed to a collecting function of a [hooks-based](/docs/api/use-drop) or [decorator-based](/docs/api/drop-target). Its methods let you get information about the drag state of a specific drop target. The specific drop target bound to that monitor is called the monitor's _owner_ below.
-**`backend`**: Required. A React DnD backend. Unless you're writing a custom one, you probably want to use the [HTML5 backend](/docs/backends/html5) that ships with React DnD.
33
+
-**`context`**: Optional. The backend context used to configure the backend. This is dependent on the backend implementation.
34
+
-**`options`**: Optional. An options object used to configure the backend. This is dependent on the backend implementation.
_New to React DnD? [Read the overview](/docs/overview) before jumping into the docs._
7
+
8
+
# Using the Hooks API
9
+
10
+
The hooks-based React DnD API leverages one of the significant newer features of React. Hooks have dramatically impacted how most people write their Reoct components, and are the recommended approach for writing stateful and effectful code within React. Prior to hooks, the React community poured a lot of effort into Higher Order Components and Decorator-based libraries. After hooks were introduced to the React community, there has been a dramatic shift in switching towards approaches and libraries that utilize hooks over decorator-based techniques.
11
+
12
+
In the overview page, it is pointed out that Drag-and-drop interations are inherently _stateful_. Because of this React DnD has been designed to take advantage of the Flux data pattern and model drag-and-drop state using actions and reducers (independent of React). Hooks are the perfect way to utilize a stateful data source in React. In fact, this is the approach taken by many state-management libraries in React!
13
+
14
+
There are three primary hooks that are provided to wire your components into React DnD, and a fourth is provided to give you a seam into React DnD (for testing or development purposes)
To explore further, read the individual hook API documentation, or check out the [hook-based examples](https://github.com/react-dnd/react-dnd/tree/main/packages/examples-hooks) on GitHub.
Copy file name to clipboardExpand all lines: packages/docsite/markdown/docs/03 Using Hooks/useDrag.md
+11-6
Original file line number
Diff line number
Diff line change
@@ -9,16 +9,21 @@ _New to React DnD? [Read the overview](/docs/overview) before jumping into the d
9
9
10
10
# useDrag
11
11
12
-
A hook to use the current component as a drag-source.
12
+
The `useDrag`hook provides a way to wire your component into the DnD system as a _drag source_. By passing in a specification object into `useDrag`, you declaratively describe the data `item` that will be passed to the DnD system, describe what props to `collect`, and more. The `useDrag` hooks returns a few key items: a set of collected props, and refs that may be attached to _drag source_ and _drag preview_ elements
13
13
14
14
```jsx
15
15
import { useDrag } from'react-dnd'
16
16
17
17
functionDraggableComponent(props) {
18
-
const [collectedProps, drag] =useDrag({
18
+
const [collected, drag, dragPreview] =useDrag({
19
19
item: { id, type }
20
20
})
21
-
return<div ref={drag}>...</div>
21
+
returncollected.isDragging?
22
+
<div ref={dragPreview>: (
23
+
<div ref={drag} {...collected}>
24
+
...
25
+
</div>
26
+
)
22
27
}
23
28
```
24
29
@@ -28,9 +33,9 @@ function DraggableComponent(props) {
28
33
29
34
#### Return Value Array
30
35
31
-
-**`Index 0`**: An object containing collected properties from the collect function. If no `collect` function is defined, an empty object is returned.
32
-
-**`Index 1`**: A connector function for the drag source. This must be attached to the draggable portion of the DOM.
33
-
-**`Index 2`**: A connector function for the drag preview. This may be attached to the preview portion of the DOM.
36
+
- **`[0] - Collected Props`**: An object containing collected properties from the collect function. If no `collect` function is defined, an empty object is returned.
37
+
- **`[1] - DragSource Ref`**: A connector function for the drag source. This must be attached to the draggable portion of the DOM.
38
+
- **`[2] - DragPreview Ref`**: A connector function for the drag preview. This may be attached to the preview portion of the DOM.
0 commit comments