0
# Core Dropzone
1

2
The main Dropzone component provides comprehensive file drag-and-drop functionality with extensive configuration options, validation, theming integration, and accessibility features.
3

4
## Capabilities
5

6
### Dropzone Component
7

8
Main file dropzone component that handles drag-and-drop file uploads with validation, theming, and extensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Main dropzone component for file drag-and-drop functionality
13
 * @param props - Configuration options for the dropzone
14
 * @returns React component with file drop functionality
15
 */
16
interface DropzoneProps extends BoxProps, StylesApiProps<DropzoneFactory>, ElementProps<'div', 'onDrop'> {
17
  /** Called when valid files are dropped to the dropzone */
18
  onDrop: (files: FileWithPath[]) => void;
19
  
20
  /** Called when dropped files do not meet file restrictions */
21
  onReject?: (fileRejections: FileRejection[]) => void;
22
  
23
  /** Called when any files are dropped to the dropzone */
24
  onDropAny?: (files: FileWithPath[], fileRejections: FileRejection[]) => void;
25
  
26
  /** Mime types of the files that dropzone can accepts. By default, dropzone accepts all file types. */
27
  accept?: Accept | string[];
28
  
29
  /** Maximum file size in bytes */
30
  maxSize?: number;
31
  
32
  /** Maximum number of files that can be picked at once */
33
  maxFiles?: number;
34
  
35
  /** Determines whether multiple files can be dropped to the dropzone or selected from file system picker @default true */
36
  multiple?: boolean;
37
  
38
  /** Determines whether files capturing should be disabled @default false */
39
  disabled?: boolean;
40
  
41
  /** Determines whether a loading overlay should be displayed over the dropzone @default false */
42
  loading?: boolean;
43
  
44
  /** Key of theme.colors or any valid CSS color to set colors of Dropzone.Accept @default theme.primaryColor */
45
  acceptColor?: MantineColor;
46
  
47
  /** Key of theme.colors or any valid CSS color to set colors of Dropzone.Reject @default 'red' */
48
  rejectColor?: MantineColor;
49
  
50
  /** Key of theme.radius or any valid CSS value to set border-radius, numbers are converted to rem @default theme.defaultRadius */
51
  radius?: MantineRadius;
52
  
53
  /** Controls dropzone appearance variant @default 'light' */
54
  variant?: DropzoneVariant;
55
  
56
  /** A ref function which when called opens the file system file picker */
57
  openRef?: React.ForwardedRef<() => void | undefined>;
58
  
59
  /** Name of the form control. Submitted with the form as part of a name/value pair. */
60
  name?: string;
61
  
62
  /** Set to autofocus the root element */
63
  autoFocus?: boolean;
64
  
65
  /** If false, disables click to open the native file selection dialog */
66
  activateOnClick?: boolean;
67
  
68
  /** If false, disables drag 'n' drop */
69
  activateOnDrag?: boolean;
70
  
71
  /** If false, disables Space/Enter to open the native file selection dialog. Note that it also stops tracking the focus state. */
72
  activateOnKeyboard?: boolean;
73
  
74
  /** If false, stops drag event propagation to parents */
75
  dragEventsBubbling?: boolean;
76
  
77
  /** Called when the dragenter event occurs */
78
  onDragEnter?: (event: React.DragEvent<HTMLElement>) => void;
79
  
80
  /** Called when the dragleave event occurs */
81
  onDragLeave?: (event: React.DragEvent<HTMLElement>) => void;
82
  
83
  /** Called when the dragover event occurs */
84
  onDragOver?: (event: React.DragEvent<HTMLElement>) => void;
85
  
86
  /** Called when user closes the file selection dialog with no selection */
87
  onFileDialogCancel?: () => void;
88
  
89
  /** Called when user opens the file selection dialog */
90
  onFileDialogOpen?: () => void;
91
  
92
  /** If false, allow dropped items to take over the current browser window */
93
  preventDropOnDocument?: boolean;
94
  
95
  /** Set to true to use the File System Access API to open the file picker instead of using an input type="file" click event @default true */
96
  useFsAccessApi?: boolean;
97
  
98
  /** Use this to provide a custom file aggregator */
99
  getFilesFromEvent?: (event: DropEvent) => Promise<Array<File | DataTransferItem>>;
100
  
101
  /** Custom validation function. It must return null if there's no errors. */
102
  validator?: <T extends File>(file: T) => FileError | FileError[] | null;
103
  
104
  /** Determines whether pointer events should be enabled on the inner element @default false */
105
  enablePointerEvents?: boolean;
106
  
107
  /** Props passed down to the Loader component */
108
  loaderProps?: LoaderProps;
109
  
110
  /** Props passed down to the internal Input component */
111
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
112
  
113
  /** Component children, typically status components */
114
  children?: React.ReactNode;
115
}
116

117
const Dropzone: React.FC<DropzoneProps> & {
118
  Accept: typeof DropzoneAccept;
119
  Idle: typeof DropzoneIdle;
120
  Reject: typeof DropzoneReject;
121
  FullScreen: typeof DropzoneFullScreen;
122
};
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { Dropzone, MIME_TYPES } from "@mantine/dropzone";
129

130
// Basic dropzone
131
function BasicDropzone() {
132
  return (
133
    <Dropzone onDrop={(files) => console.log(files)}>
134
      <div>Drop files here</div>
135
    </Dropzone>
136
  );
137
}
138

139
// Dropzone with file type restrictions
140
function ImageDropzone() {
141
  return (
142
    <Dropzone
143
      onDrop={(files) => console.log('accepted', files)}
144
      onReject={(files) => console.log('rejected', files)}
145
      maxSize={3 * 1024 ** 2} // 3MB
146
      accept={[MIME_TYPES.png, MIME_TYPES.jpeg, MIME_TYPES.gif]}
147
    >
148
      <Dropzone.Accept>
149
        <Text>Drop images here</Text>
150
      </Dropzone.Accept>
151
      <Dropzone.Reject>
152
        <Text color="red">Only images under 3MB are accepted</Text>
153
      </Dropzone.Reject>
154
      <Dropzone.Idle>
155
        <Text>Drop images or click to select files</Text>
156
      </Dropzone.Idle>
157
    </Dropzone>
158
  );
159
}
160

161
// Dropzone with custom validation
162
function CustomValidationDropzone() {
163
  const validator = (file: File) => {
164
    if (file.name.includes('virus')) {
165
      return { code: 'name-not-allowed', message: 'File name not allowed' };
166
    }
167
    return null;
168
  };
169

170
  return (
171
    <Dropzone
172
      onDrop={(files) => console.log(files)}
173
      validator={validator}
174
      multiple={false}
175
    >
176
      <div>Drop a single file here</div>
177
    </Dropzone>
178
  );
179
}
180

181
// Dropzone with loading state
182
function LoadingDropzone() {
183
  const [loading, setLoading] = useState(false);
184

185
  const handleDrop = async (files: FileWithPath[]) => {
186
    setLoading(true);
187
    // Simulate upload
188
    await new Promise(resolve => setTimeout(resolve, 2000));
189
    setLoading(false);
190
  };
191

192
  return (
193
    <Dropzone onDrop={handleDrop} loading={loading}>
194
      <div>Drop files to upload</div>
195
    </Dropzone>
196
  );
197
}
198

199
// Dropzone with programmatic file selection
200
function ProgrammaticDropzone() {
201
  const openRef = useRef<() => void>(null);
202

203
  return (
204
    <div>
205
      <Button onClick={() => openRef.current?.()}>
206
        Open file picker
207
      </Button>
208
      
209
      <Dropzone
210
        onDrop={(files) => console.log(files)}
211
        openRef={openRef}
212
        activateOnClick={false}
213
      >
214
        <div>Files will appear here</div>
215
      </Dropzone>
216
    </div>
217
  );
218
}
219
```
220

221
### Default Props
222

223
The Dropzone component comes with sensible defaults:
224

225
```typescript { .api }
226
const defaultProps = {
227
  multiple: true,
228
  maxSize: Infinity,
229
  activateOnClick: true,
230
  activateOnDrag: true,
231
  dragEventsBubbling: true,
232
  activateOnKeyboard: true,
233
  useFsAccessApi: true,
234
  variant: 'light',
235
  rejectColor: 'red',
236
};
237
```
238

239
### Static Components
240

241
The Dropzone component includes static status components as properties:
242

243
```typescript { .api }
244
Dropzone.Accept: typeof DropzoneAccept;
245
Dropzone.Idle: typeof DropzoneIdle;
246
Dropzone.Reject: typeof DropzoneReject;
247
Dropzone.FullScreen: typeof DropzoneFullScreen;
248
```
249

250
### Integration with react-dropzone
251

252
The component is built on top of react-dropzone and exposes most of its configuration options through props. The underlying `useDropzone` hook is used internally to provide the drag-and-drop functionality.
253

254
### Theming and Styling
255

256
The component supports Mantine's theming system with customizable colors, radius, and CSS variables. It uses the Factory pattern for consistent styling API across Mantine components.
257

258
### Error Handling
259

260
File validation errors are handled through the `onReject` callback, which receives an array of `FileRejection` objects containing the rejected files and their associated errors.