0
# Drag Preview Utilities
1

2
Utilities for customizing drag preview behavior, specifically the creation of transparent images to hide the default browser drag preview and enable custom drag preview implementations.
3

4
## Capabilities
5

6
### Empty Image Creation
7

8
Create a transparent 1x1 pixel image for hiding the default browser drag preview, allowing for custom drag preview implementations.
9

10
```typescript { .api }
11
/**
12
 * Returns a transparent 1x1 pixel image for drag preview customization
13
 * The image is cached and reused across calls for performance
14
 * @returns HTMLImageElement with transparent GIF data
15
 */
16
function getEmptyImage(): HTMLImageElement;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { useDragPreview } from "react-dnd";
23
import { getEmptyImage } from "react-dnd-html5-backend";
24
import { useEffect } from "react";
25

26
// Hide default drag preview to show custom preview
27
function DragSourceWithCustomPreview() {
28
  const [, drag, preview] = useDrag({
29
    type: "ITEM",
30
    item: { id: "123", name: "Custom Item" },
31
  });
32

33
  // Hide the default browser drag preview
34
  useEffect(() => {
35
    preview(getEmptyImage(), { captureDraggingState: true });
36
  }, [preview]);
37

38
  return (
39
    <div ref={drag} style={{ cursor: "move" }}>
40
      Drag me (custom preview will show)
41
    </div>
42
  );
43
}
44

45
// Connect empty image immediately
46
function SimpleCustomPreview() {
47
  const [, drag, preview] = useDrag({
48
    type: "ITEM",
49
    item: { id: "456" },
50
  });
51

52
  // Connect empty image to hide default preview
53
  const emptyImage = getEmptyImage();
54
  preview(emptyImage);
55

56
  return <div ref={drag}>Drag with no default preview</div>;
57
}
58

59
// Use with custom drag layer for complete control
60
function CustomDragLayer() {
61
  const [, drag, preview] = useDrag({
62
    type: "CUSTOM_ITEM",
63
    item: { id: "custom" },
64
  });
65

66
  // Hide native preview and use custom drag layer
67
  useEffect(() => {
68
    preview(getEmptyImage(), { captureDraggingState: true });
69
  }, [preview]);
70

71
  return <div ref={drag}>Drag with custom layer</div>;
72
}
73
```
74

75
### Preview Positioning Options
76

77
When using `getEmptyImage()` with React DnD's preview connection, you can provide positioning options:
78

79
```typescript { .api }
80
interface DragPreviewOptions {
81
  /** Horizontal anchor point (0 = left edge, 0.5 = center, 1 = right edge) */
82
  anchorX?: number;
83
  /** Vertical anchor point (0 = top edge, 0.5 = center, 1 = bottom edge) */
84
  anchorY?: number;
85
  /** Manual horizontal offset in pixels (overrides anchor-based positioning) */
86
  offsetX?: number;
87
  /** Manual vertical offset in pixels (overrides anchor-based positioning) */
88
  offsetY?: number;
89
  /** Whether to capture the dragging state for the preview */
90
  captureDraggingState?: boolean;
91
}
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
import { useDrag } from "react-dnd";
98
import { getEmptyImage } from "react-dnd-html5-backend";
99

100
// Different anchor point configurations
101
function AnchorPointExamples() {
102
  const [, drag1, preview1] = useDrag({ type: "TOP_LEFT", item: {} });
103
  const [, drag2, preview2] = useDrag({ type: "CENTER", item: {} });
104
  const [, drag3, preview3] = useDrag({ type: "BOTTOM_RIGHT", item: {} });
105

106
  // Top-left anchored preview
107
  preview1(getEmptyImage(), { anchorX: 0, anchorY: 0 });
108
  
109
  // Center anchored preview  
110
  preview2(getEmptyImage(), { anchorX: 0.5, anchorY: 0.5 });
111
  
112
  // Bottom-right anchored preview
113
  preview3(getEmptyImage(), { anchorX: 1, anchorY: 1 });
114

115
  return (
116
    <div>
117
      <div ref={drag1}>Top-Left Anchor</div>
118
      <div ref={drag2}>Center Anchor</div>
119
      <div ref={drag3}>Bottom-Right Anchor</div>
120
    </div>
121
  );
122
}
123

124
// Manual offset positioning
125
function ManualOffsetExample() {
126
  const [, drag, preview] = useDrag({
127
    type: "MANUAL_OFFSET",
128
    item: { id: "manual" },
129
  });
130

131
  // Position preview 20px right and 10px down from cursor
132
  preview(getEmptyImage(), {
133
    offsetX: 20,
134
    offsetY: 10,
135
    captureDraggingState: true,
136
  });
137

138
  return <div ref={drag}>Drag with manual offset</div>;
139
}
140

141
// Capture dragging state for custom drag layers
142
function DragStateCapture() {
143
  const [, drag, preview] = useDrag({
144
    type: "STATE_CAPTURE",
145
    item: { id: "state" },
146
  });
147

148
  // Enable dragging state capture for custom drag layer integration
149
  preview(getEmptyImage(), {
150
    captureDraggingState: true,
151
  });
152

153
  return <div ref={drag}>Drag with state capture</div>;
154
}
155
```
156

157
## Implementation Details
158

159
- The `getEmptyImage()` function returns a cached HTMLImageElement containing a transparent 1x1 pixel GIF
160
- The same image instance is reused across multiple calls for optimal performance
161
- The transparent image effectively hides the browser's default drag preview
162
- Most commonly used in conjunction with custom drag layers for complete visual control
163
- Compatible with all positioning options supported by React DnD's preview connections