0
# Plate DnD
1

2
The @udecode/plate-dnd package provides comprehensive drag-and-drop functionality for the Plate rich-text editor. It enables users to rearrange editor blocks through intuitive drag-and-drop interactions, with features including visual drop indicators, automatic viewport scrolling during drag operations, customizable drag handles, and support for file drops to insert media content. The plugin integrates seamlessly with React DnD backend and provides hooks for managing drag states, drop zones, and node interactions.
3

4
## Package Information
5

6
- **Package Name**: @udecode/plate-dnd
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @udecode/plate-dnd`
10

11
## Core Imports
12

13
```typescript
14
import { DndPlugin, useDndNode, useDraggable, useDropLine } from "@udecode/plate-dnd";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { DndPlugin, useDndNode, useDraggable, useDropLine } = require("@udecode/plate-dnd");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { DndPlugin, useDndNode } from "@udecode/plate-dnd";
27
import { createPlateEditor } from "@udecode/plate/react";
28

29
// Configure the plugin
30
const editor = createPlateEditor({
31
  plugins: [
32
    DndPlugin.configure({
33
      options: {
34
        enableScroller: true,
35
        onDropFiles: ({ id, dragItem, editor, target }) => {
36
          // Handle file drops to insert media
37
          console.log('File dropped:', dragItem.files);
38
        }
39
      }
40
    })
41
  ]
42
});
43

44
// Use in a block component
45
function DraggableBlock({ element, children }) {
46
  const { dragRef, isDragging, isOver } = useDndNode({
47
    element,
48
    orientation: 'vertical'
49
  });
50

51
  return (
52
    <div 
53
      ref={dragRef}
54
      style={{ opacity: isDragging ? 0.5 : 1 }}
55
    >
56
      {children}
57
    </div>
58
  );
59
}
60
```
61

62
## Architecture
63

64
The @udecode/plate-dnd package is built around several key components:
65

66
- **Plugin System**: Core `DndPlugin` integrating with Plate's plugin architecture
67
- **React DnD Integration**: Built on react-dnd for robust drag-and-drop behavior
68
- **Hook-based API**: Composable hooks for different aspects of drag-and-drop
69
- **Auto-scrolling**: Smart viewport scrolling during drag operations
70
- **Type Safety**: Full TypeScript support with comprehensive type definitions
71
- **File Drop Support**: Native browser file drop handling for media insertion
72

73
## Capabilities
74

75
### Plugin Configuration
76

77
The core DndPlugin that integrates drag-and-drop functionality into Plate editors, with configurable options for behavior customization.
78

79
```typescript { .api }
80
export const DndPlugin: PlatePlugin<DndConfig>;
81

82
export type DndConfig = PluginConfig<
83
  'dnd',
84
  {
85
    draggingId?: string | null;
86
    dropTarget?: {
87
      id: string | null;
88
      line: DropLineDirection;
89
    };
90
    enableScroller?: boolean;
91
    isDragging?: boolean;
92
    scrollerProps?: Partial<ScrollerProps>;
93
    onDropFiles?: (props: {
94
      id: string;
95
      dragItem: FileDragItemNode;
96
      editor: PlateEditor;
97
      monitor: DropTargetMonitor<DragItemNode, unknown>;
98
      nodeRef: any;
99
      target?: Path;
100
    }) => void;
101
  }
102
>;
103

104
export const DRAG_ITEM_BLOCK = 'block';
105
```
106

107
[Plugin Configuration](./plugin-configuration.md)
108

109
### Drag and Drop Hooks
110

111
React hooks for implementing drag-and-drop behavior on editor nodes, with support for both dragging and dropping functionality.
112

113
```typescript { .api }
114
export function useDndNode(options: UseDndNodeOptions): {
115
  dragRef: ConnectDragSource;
116
  isDragging: boolean;
117
  isOver: boolean;
118
};
119

120
export function useDragNode(
121
  editor: PlateEditor,
122
  options: UseDragNodeOptions
123
): [{ isDragging: boolean }, ConnectDragSource, ConnectDragPreview];
124

125
export function useDropNode(
126
  editor: PlateEditor,
127
  options: UseDropNodeOptions
128
): [{ isOver: boolean }, ConnectDropTarget];
129
```
130

131
[Drag and Drop Hooks](./drag-drop-hooks.md)
132

133
### Component Utilities
134

135
Pre-built components and hooks for common drag-and-drop UI patterns including draggable elements and drop line indicators.
136

137
```typescript { .api }
138
export function useDraggable(props: UseDndNodeOptions): DraggableState;
139

140
export function useDropLine(options?: {
141
  id?: string;
142
  orientation?: 'horizontal' | 'vertical';
143
}): {
144
  dropLine?: DropLineDirection;
145
};
146

147
export type DraggableState = {
148
  isDragging: boolean;
149
  previewRef: React.RefObject<HTMLDivElement | null>;
150
  handleRef: (elementOrNode: Element | React.ReactElement<any> | React.RefObject<any> | null) => void;
151
};
152
```
153

154
[Component Utilities](./component-utilities.md)
155

156
### Auto-scrolling Components
157

158
Components that provide automatic viewport scrolling when dragging near screen edges, enhancing user experience during drag operations.
159

160
```typescript { .api }
161
export function DndScroller(props: Partial<ScrollerProps>): JSX.Element;
162

163
export function Scroller(props: ScrollerProps): JSX.Element;
164

165
export function ScrollArea({
166
  placement,
167
  containerRef,
168
  enabled,
169
  height,
170
  minStrength,
171
  scrollAreaProps,
172
  strengthMultiplier,
173
  zIndex
174
}: ScrollAreaProps): JSX.Element | null;
175
```
176

177
[Auto-scrolling Components](./auto-scrolling.md)
178

179
### Editor Transforms
180

181
Functions for manipulating editor state during drag-and-drop operations, including block selection, movement, and focus management.
182

183
```typescript { .api }
184
export function selectBlocksBySelectionOrId(editor: PlateEditor, id: string): void;
185

186
export function selectBlockById(editor: Editor, id: string): void;
187

188
export function removeBlocksAndFocus<E extends Editor = Editor>(
189
  editor: E,
190
  options: EditorNodesOptions<ValueOf<E>>
191
): void;
192

193
export function focusBlockStartById(editor: Editor, id: string): void;
194

195
export function onDropNode(
196
  editor: PlateEditor,
197
  options: OnDropNodeOptions
198
): void;
199
```
200

201
[Editor Transforms](./editor-transforms.md)
202

203
### Utility Functions
204

205
Helper functions for calculating drop directions, handling hover states, and determining valid drop operations.
206

207
```typescript { .api }
208
export function getHoverDirection(options: GetHoverDirectionOptions): string;
209

210
export function getNewDirection(
211
  previousDir: string,
212
  dir?: string
213
): DropLineDirection | undefined;
214

215
export function getBlocksWithId<E extends Editor>(
216
  editor: E,
217
  options: EditorNodesOptions<ValueOf<E>>
218
): NodeEntry<TElement>[];
219
```
220

221
[Utility Functions](./utility-functions.md)
222

223
## Types
224

225
```typescript { .api }
226
export type DragItemNode = ElementDragItemNode | FileDragItemNode;
227

228
export type DropDirection = 'bottom' | 'left' | 'right' | 'top' | undefined;
229

230
export type DropLineDirection = '' | 'bottom' | 'left' | 'right' | 'top';
231

232
export interface ElementDragItemNode {
233
  id: string;
234
  element: TElement;
235
  [key: string]: unknown;
236
}
237

238
export interface FileDragItemNode {
239
  dataTransfer: DataTransfer[];
240
  files: FileList;
241
  items: DataTransferItemList;
242
}
243
```