0
# Configuration
1

2
Comprehensive configuration options for customizing @uppy/dashboard appearance, behavior, and features.
3

4
## Capabilities
5

6
### Dashboard Options Interface
7

8
Main configuration interface combining modal/inline options with miscellaneous settings.
9

10
```typescript { .api }
11
/**
12
 * Main configuration interface for Dashboard plugin
13
 * Combines modal/inline options with miscellaneous settings
14
 */
15
type DashboardOptions<M extends Meta, B extends Body> = 
16
  DashboardMiscOptions<M, B> & 
17
  (DashboardModalOptions | DashboardInlineOptions);
18
```
19

20
### Modal Configuration
21

22
Options specific to modal (overlay) mode dashboard.
23

24
```typescript { .api }
25
/**
26
 * Configuration options for modal dashboard mode
27
 */
28
interface DashboardModalOptions {
29
  /** Indicates modal mode (default: false) */
30
  inline?: false;
31
  /** Enable open/close animations (default: true) */
32
  animateOpenClose?: boolean;
33
  /** Close modal with browser back button (default: false) */
34
  browserBackButtonClose?: boolean;
35
  /** Auto-close modal after upload completion (default: false) */
36
  closeAfterFinish?: boolean;
37
  /** Close modal when clicking outside (default: false) */
38
  closeModalOnClickOutside?: boolean;
39
  /** Disable page scroll when modal open (default: true) */
40
  disablePageScrollWhenModalOpen?: boolean;
41
}
42
```
43

44
### Inline Configuration
45

46
Options specific to inline (embedded) mode dashboard.
47

48
```typescript { .api }
49
/**
50
 * Configuration options for inline dashboard mode
51
 */
52
interface DashboardInlineOptions {
53
  /** Indicates inline mode (required: true) */
54
  inline: true;
55
  /** Container height in pixels or CSS string (default: 550) */
56
  height?: string | number;
57
  /** Container width in pixels or CSS string (default: 750) */
58
  width?: string | number;
59
}
60
```
61

62
### UI Configuration Options
63

64
Core user interface and appearance settings.
65

66
```typescript { .api }
67
/**
68
 * UI and appearance configuration options
69
 */
70
interface DashboardUIOptions {
71
  /** Auto-open editor type on file selection */
72
  autoOpen?: 'metaEditor' | 'imageEditor' | null;
73
  /** Default picker icon component */
74
  defaultPickerIcon?: typeof defaultPickerIcon;
75
  /** Disable all dashboard interactions (default: false) */
76
  disabled?: boolean;
77
  /** Disable informer component (default: false) */
78
  disableInformer?: boolean;
79
  /** Disable local file selection (default: false) */
80
  disableLocalFiles?: boolean;
81
  /** Disable status bar component (default: false) */
82
  disableStatusBar?: boolean;
83
  /** Disable thumbnail generation (default: false) */
84
  disableThumbnailGenerator?: boolean;
85
  /** UI theme selection (default: 'light') */
86
  theme?: 'auto' | 'dark' | 'light';
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import Dashboard from "@uppy/dashboard";
94

95
// Auto theme with system preference
96
uppy.use(Dashboard, {
97
  theme: "auto", // Automatically switches with system preference
98
  disabled: false,
99
  disableStatusBar: false
100
});
101

102
// Dark theme with disabled informer
103
uppy.use(Dashboard, {
104
  theme: "dark",
105
  disableInformer: true,
106
  autoOpen: "metaEditor"
107
});
108
```
109

110
### File Management Options
111

112
Configuration for file selection, display, and management behavior.
113

114
```typescript { .api }
115
/**
116
 * File management and display configuration
117
 */
118
interface DashboardFileOptions<M extends Meta, B extends Body> {
119
  /** Selection type for file manager */
120
  fileManagerSelectionType?: 'files' | 'folders' | 'both';
121
  /** Metadata fields configuration */
122
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
123
  /** Show selected files list (default: true) */
124
  showSelectedFiles?: boolean;
125
  /** Full screen for single file (default: true) */
126
  singleFileFullScreen?: boolean;
127
  /** Wait for thumbnails before upload (default: false) */
128
  waitForThumbnailsBeforeUpload?: boolean;
129
}
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
// Static metadata fields
136
uppy.use(Dashboard, {
137
  metaFields: [
138
    { id: "name", name: "Name", placeholder: "Enter file name" },
139
    { id: "caption", name: "Caption" }
140
  ],
141
  fileManagerSelectionType: "both"
142
});
143

144
// Dynamic metadata fields based on file type
145
uppy.use(Dashboard, {
146
  metaFields: (file) => {
147
    if (file.type?.startsWith("image/")) {
148
      return [
149
        { id: "alt", name: "Alt Text", placeholder: "Describe the image" },
150
        { id: "title", name: "Title" }
151
      ];
152
    }
153
    return [{ id: "description", name: "Description" }];
154
  }
155
});
156
```
157

158
### Button Visibility Options
159

160
Control visibility of various UI buttons and elements.
161

162
```typescript { .api }
163
/**
164
 * Button visibility configuration options
165
 */
166
interface DashboardButtonOptions {
167
  /** Hide cancel button (default: false) */
168
  hideCancelButton?: boolean;
169
  /** Hide pause/resume button (default: false) */
170
  hidePauseResumeButton?: boolean;
171
  /** Hide progress after completion (default: false) */
172
  hideProgressAfterFinish?: boolean;
173
  /** Hide retry button (default: false) */
174
  hideRetryButton?: boolean;
175
  /** Hide upload button (default: false) */
176
  hideUploadButton?: boolean;
177
  /** Hide detailed progress information (default: false) */
178
  hideProgressDetails?: boolean;
179
  /** Show link to upload result (default: false) */
180
  showLinkToFileUploadResult?: boolean;
181
  /** Show native photo camera button (default: false) */
182
  showNativePhotoCameraButton?: boolean;
183
  /** Show native video camera button (default: false) */
184
  showNativeVideoCameraButton?: boolean;
185
  /** Show remove button after completion (default: false) */
186
  showRemoveButtonAfterComplete?: boolean;
187
}
188
```
189

190
### Thumbnail Configuration
191

192
Options for thumbnail generation and display.
193

194
```typescript { .api }
195
/**
196
 * Thumbnail generation and display configuration
197
 */
198
interface DashboardThumbnailOptions {
199
  /** Thumbnail height in pixels */
200
  thumbnailHeight?: number;
201
  /** Thumbnail MIME type (default: 'image/jpeg') */
202
  thumbnailType?: string;
203
  /** Thumbnail width in pixels (default: 280) */
204
  thumbnailWidth?: number;
205
}
206
```
207

208
### Event Callback Configuration
209

210
Configure event handlers for user interactions and lifecycle events.
211

212
```typescript { .api }
213
/**
214
 * Event callback configuration options
215
 */
216
interface DashboardCallbackOptions {
217
  /** Done button click handler (null disables button) */
218
  doneButtonHandler?: null | (() => void);
219
  /** Drag leave event handler */
220
  onDragLeave?: (event: DragEvent) => void;
221
  /** Drag over event handler */
222
  onDragOver?: (event: DragEvent) => void;
223
  /** Drop event handler */
224
  onDrop?: (event: DragEvent) => void;
225
  /** Modal close request handler */
226
  onRequestCloseModal?: () => void;
227
}
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
uppy.use(Dashboard, {
234
  // Custom done button behavior
235
  doneButtonHandler: () => {
236
    console.log("Upload completed!");
237
    // Custom cleanup or navigation logic
238
  },
239
  
240
  // Custom drag and drop handlers
241
  onDragOver: (event) => {
242
    console.log("Files being dragged over dashboard");
243
  },
244
  
245
  onDrop: (event) => {
246
    console.log("Files dropped on dashboard");
247
  }
248
});
249
```
250

251
### Camera and Device Options
252

253
Configuration for native device camera integration.
254

255
```typescript { .api }
256
/**
257
 * Camera and native device configuration
258
 */
259
interface DashboardCameraOptions {
260
  /** Native camera facing mode */
261
  nativeCameraFacingMode?: 'user' | 'environment' | '';
262
}
263
```
264

265
### Additional Options
266

267
Miscellaneous configuration options for plugins, triggers, and localization.
268

269
```typescript { .api }
270
/**
271
 * Additional configuration options
272
 */
273
interface DashboardMiscOptions {
274
  /** Note text to display in dashboard */
275
  note?: string | null;
276
  /** Array of plugin IDs to include */
277
  plugins?: string[];
278
  /** Show "powered by Uppy" text (default: true) */
279
  proudlyDisplayPoweredByUppy?: boolean;
280
  /** Element/selector to trigger modal opening */
281
  trigger?: string | Element | null;
282
  /** Localization strings */
283
  locale?: LocaleStrings<typeof locale>;
284
}
285
```
286

287
### Complete Options Interface
288

289
The complete miscellaneous options interface combining all configuration categories.
290

291
```typescript { .api }
292
/**
293
 * Complete miscellaneous options interface
294
 * Extends UIPluginOptions from @uppy/core
295
 */
296
interface DashboardMiscOptions<M extends Meta, B extends Body> extends UIPluginOptions {
297
  // UI Options
298
  autoOpen?: 'metaEditor' | 'imageEditor' | null;
299
  defaultPickerIcon?: typeof defaultPickerIcon;
300
  disabled?: boolean;
301
  disableInformer?: boolean;
302
  disableLocalFiles?: boolean;
303
  disableStatusBar?: boolean;
304
  disableThumbnailGenerator?: boolean;
305
  theme?: 'auto' | 'dark' | 'light';
306
  
307
  // File Management
308
  fileManagerSelectionType?: 'files' | 'folders' | 'both';
309
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
310
  showSelectedFiles?: boolean;
311
  singleFileFullScreen?: boolean;
312
  waitForThumbnailsBeforeUpload?: boolean;
313
  
314
  // Button Visibility
315
  hideCancelButton?: boolean;
316
  hidePauseResumeButton?: boolean;
317
  hideProgressAfterFinish?: boolean;
318
  hideRetryButton?: boolean;
319
  hideUploadButton?: boolean;
320
  hideProgressDetails?: boolean;
321
  showLinkToFileUploadResult?: boolean;
322
  showNativePhotoCameraButton?: boolean;
323
  showNativeVideoCameraButton?: boolean;
324
  showRemoveButtonAfterComplete?: boolean;
325
  
326
  // Thumbnails
327
  thumbnailHeight?: number;
328
  thumbnailType?: string;
329
  thumbnailWidth?: number;
330
  
331
  // Event Callbacks
332
  doneButtonHandler?: null | (() => void);
333
  onDragLeave?: (event: DragEvent) => void;
334
  onDragOver?: (event: DragEvent) => void;
335
  onDrop?: (event: DragEvent) => void;
336
  onRequestCloseModal?: () => void;
337
  
338
  // Camera
339
  nativeCameraFacingMode?: 'user' | 'environment' | '';
340
  
341
  // Miscellaneous  
342
  note?: string | null;
343
  plugins?: string[];
344
  proudlyDisplayPoweredByUppy?: boolean;
345
  trigger?: string | Element | null;
346
  locale?: LocaleStrings<typeof locale>;
347
}
348
```
349

350
### Default Configuration Values
351

352
Default values applied when options are not specified.
353

354
```typescript { .api }
355
/**
356
 * Default configuration values
357
 */
358
const defaultOptions = {
359
  // Modal Options
360
  inline: false,
361
  animateOpenClose: true,
362
  browserBackButtonClose: false,
363
  closeAfterFinish: false,
364
  closeModalOnClickOutside: false,
365
  disablePageScrollWhenModalOpen: true,
366
  trigger: null,
367
  
368
  // Inline Options  
369
  width: 750,
370
  height: 550,
371
  
372
  // UI Options
373
  target: 'body',
374
  theme: 'light',
375
  autoOpen: null,
376
  disabled: false,
377
  disableInformer: false,
378
  disableLocalFiles: false,
379
  disableStatusBar: false,
380
  disableThumbnailGenerator: false,
381
  
382
  // File Management
383
  metaFields: [],
384
  fileManagerSelectionType: 'files',
385
  showSelectedFiles: true,
386
  singleFileFullScreen: true,
387
  waitForThumbnailsBeforeUpload: false,
388
  
389
  // Button Visibility
390
  hideUploadButton: false,
391
  hideCancelButton: false,
392
  hideRetryButton: false,
393
  hidePauseResumeButton: false,
394
  hideProgressAfterFinish: false,
395
  hideProgressDetails: false,
396
  showLinkToFileUploadResult: false,
397
  showRemoveButtonAfterComplete: false,
398
  showNativePhotoCameraButton: false,
399
  showNativeVideoCameraButton: false,
400
  
401
  // Thumbnails
402
  thumbnailWidth: 280,
403
  thumbnailType: 'image/jpeg',
404
  
405
  // Other
406
  note: null,
407
  plugins: [],
408
  proudlyDisplayPoweredByUppy: true,
409
  nativeCameraFacingMode: ''
410
};
411
```
412

413
### Set Dark Mode Capability
414

415
Configure dashboard's dark mode capability in Uppy core state.
416

417
```typescript { .api }
418
/**
419
 * Set dark mode capability
420
 * Updates Uppy core state to reflect dark mode availability
421
 * @param isDarkModeOn - Whether dark mode is currently enabled
422
 */
423
setDarkModeCapability(isDarkModeOn: boolean): void;
424
```
425

426
**Usage Examples:**
427

428
```typescript
429
// Enable dark mode capability
430
dashboard.setDarkModeCapability(true);
431

432
// Disable dark mode capability  
433
dashboard.setDarkModeCapability(false);
434

435
// Respond to system theme changes
436
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
437
mediaQuery.addEventListener('change', (e) => {
438
  dashboard.setDarkModeCapability(e.matches);
439
});
440
```
441

442
### setOptions Method
443

444
Update dashboard configuration at runtime.
445

446
```typescript { .api }
447
/**
448
 * Update dashboard options at runtime
449
 * @param opts - Partial configuration options to update
450
 */
451
setOptions(opts: Partial<DashboardOptions<M, B>>): void;
452
```
453

454
**Usage Examples:**
455

456
```typescript
457
// Update theme dynamically
458
dashboard.setOptions({ theme: "dark" });
459

460
// Enable progress details
461
dashboard.setOptions({ 
462
  hideProgressDetails: false,
463
  showLinkToFileUploadResult: true 
464
});
465

466
// Update metadata fields
467
dashboard.setOptions({
468
  metaFields: [
469
    { id: "title", name: "Title", placeholder: "Enter title" },
470
    { id: "description", name: "Description" }
471
  ]
472
});
473
```