0
# UI Plugins
1

2
UI plugins provide user interface components for file selection, display, and interaction. These plugins extend UIPlugin and render visual components that users interact with during the upload process.
3

4
## Capabilities
5

6
### Dashboard
7

8
Comprehensive dashboard UI providing the complete Uppy experience with file management, previews, and upload controls.
9

10
```typescript { .api }
11
/**
12
 * Main dashboard UI plugin with full feature set
13
 */
14
class Dashboard<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DashboardOptions<M, B>> {
15
  constructor(uppy: Uppy<M, B>, options?: DashboardOptions<M, B>);
16
  
17
  // Modal operations
18
  openModal(): Promise<void>;
19
  closeModal(options?: { manualClose?: boolean }): void | Promise<void>;
20
  isModalOpen(): boolean;
21
  
22
  // File operations
23
  addFiles(files: File[]): void;
24
  openFileEditor(file: UppyFile<M, B>): void;
25
  closeFileEditor(): void;
26
  saveFileEditor(): void;
27
  
28
  // Panel management
29
  showPanel(id: string): void;
30
  hideAllPanels(): void;
31
  toggleFileCard(show: boolean, fileID: string): void;
32
  
33
  // Plugin integration
34
  addTarget(plugin: BasePlugin<any>): HTMLElement | null;
35
  removeTarget(plugin: BasePlugin<any>): void;
36
}
37

38
interface DashboardOptions<M extends Meta = {}, B extends Body = {}> {
39
  target?: string | Element;
40
  inline?: boolean;
41
  width?: number | string;
42
  height?: number | string;
43
  trigger?: string | Element;
44
  closeAfterFinish?: boolean;
45
  theme?: 'light' | 'dark' | 'auto';
46
  note?: string;
47
  proudlyDisplayPoweredByUppy?: boolean;
48
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
49
  showProgressDetails?: boolean;
50
  showRemoveButtonAfterComplete?: boolean;
51
  browserBackButtonClose?: boolean;
52
  doneButtonHandler?: () => void;
53
}
54
```
55

56
**Usage Example:**
57

58
```typescript
59
import { Uppy, Dashboard } from "uppy";
60

61
const uppy = new Uppy()
62
  .use(Dashboard, {
63
    target: '#uppy-dashboard',
64
    inline: true,
65
    width: '100%',
66
    height: 400,
67
    theme: 'auto',
68
    showProgressDetails: true,
69
    metaFields: [
70
      { id: 'name', name: 'Name', placeholder: 'File name' },
71
      { id: 'caption', name: 'Caption', placeholder: 'Describe your file' }
72
    ]
73
  });
74
```
75

76
### File Input Components
77

78
Simple file input components for basic file selection without advanced UI features.
79

80
```typescript { .api }
81
/**
82
 * Traditional file input button
83
 */
84
class FileInput<M extends Meta = {}, B extends Body = {}> extends UIPlugin<FileInputOptions> {
85
  constructor(uppy: Uppy<M, B>, options?: FileInputOptions);
86
}
87

88
interface FileInputOptions {
89
  target?: string | Element;
90
  pretty?: boolean;
91
  inputName?: string;
92
  locale?: Locale;
93
}
94

95
/**
96
 * Drag and drop area for file selection
97
 */
98
class DragDrop<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DragDropOptions> {
99
  constructor(uppy: Uppy<M, B>, options?: DragDropOptions);
100
}
101

102
interface DragDropOptions {
103
  target?: string | Element;
104
  width?: number | string;
105
  height?: number | string;
106
  note?: string;
107
  locale?: Locale;
108
}
109

110
/**
111
 * Drop target overlay for drag and drop anywhere on page
112
 */
113
class DropTarget<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DropTargetOptions> {
114
  constructor(uppy: Uppy<M, B>, options?: DropTargetOptions);
115
}
116

117
interface DropTargetOptions {
118
  target?: string | Element;
119
  onDragOver?: (event: DragEvent) => void;
120
  onDragLeave?: (event: DragEvent) => void;
121
  onDrop?: (event: DragEvent) => void;
122
}
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
// Simple file input
129
uppy.use(FileInput, {
130
  target: '#file-input',
131
  pretty: true,
132
  inputName: 'files'
133
});
134

135
// Drag and drop area
136
uppy.use(DragDrop, {
137
  target: '#drag-drop-area',
138
  width: '100%',
139
  height: '200px',
140
  note: 'Drop files here or click to browse'
141
});
142

143
// Full-page drop target
144
uppy.use(DropTarget, {
145
  target: document.body,
146
  onDragOver: (event) => {
147
    console.log('File dragged over page');
148
  }
149
});
150
```
151

152
### Progress Display Components
153

154
Components for displaying upload progress and status information.
155

156
```typescript { .api }
157
/**
158
 * Progress bar showing upload progress
159
 */
160
class ProgressBar<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ProgressBarOptions> {
161
  constructor(uppy: Uppy<M, B>, options?: ProgressBarOptions);
162
}
163

164
interface ProgressBarOptions {
165
  target?: string | Element;
166
  fixed?: boolean;
167
  hideAfterFinish?: boolean;
168
  locale?: Locale;
169
}
170

171
/**
172
 * Status bar with detailed upload information
173
 */
174
class StatusBar<M extends Meta = {}, B extends Body = {}> extends UIPlugin<StatusBarOptions<M, B>> {
175
  constructor(uppy: Uppy<M, B>, options?: StatusBarOptions<M, B>);
176
}
177

178
interface StatusBarOptions<M extends Meta = {}, B extends Body = {}> {
179
  target?: string | Element;
180
  hideUploadButton?: boolean;
181
  hideRetryButton?: boolean;
182
  hidePauseResumeButton?: boolean;
183
  hideCancelButton?: boolean;
184
  showProgressDetails?: boolean;
185
  hideAfterFinish?: boolean;
186
  doneButtonHandler?: () => void;
187
  locale?: Locale;
188
}
189

190
/**
191
 * Information and notification display
192
 */
193
class Informer<M extends Meta = {}, B extends Body = {}> extends UIPlugin<InformerOptions> {
194
  constructor(uppy: Uppy<M, B>, options?: InformerOptions);
195
}
196

197
interface InformerOptions {
198
  target?: string | Element;
199
  replaceTargetContent?: boolean;
200
  locale?: Locale;
201
}
202
```
203

204
**Usage Examples:**
205

206
```typescript
207
// Progress bar at top of page
208
uppy.use(ProgressBar, {
209
  target: 'body',
210
  fixed: true,
211
  hideAfterFinish: true
212
});
213

214
// Detailed status bar
215
uppy.use(StatusBar, {
216
  target: '#status-bar',
217
  showProgressDetails: true,
218
  hideUploadButton: false,
219
  doneButtonHandler: () => {
220
    console.log('Upload completed!');
221
    window.location.href = '/success';
222
  }
223
});
224

225
// Notification informer
226
uppy.use(Informer, {
227
  target: '#notifications',
228
  replaceTargetContent: false
229
});
230
```
231

232
## UI Plugin Events
233

234
```typescript { .api }
235
// Dashboard-specific events
236
interface DashboardEvents<M extends Meta = {}, B extends Body = {}> {
237
  'dashboard:modal-open': () => void;
238
  'dashboard:modal-closed': () => void;
239
  'dashboard:show-panel': (id: string) => void;
240
  'dashboard:close-panel': (id: string | undefined) => void;
241
  'dashboard:file-edit-start': (file?: UppyFile<M, B>) => void;
242
  'dashboard:file-edit-complete': (file?: UppyFile<M, B>) => void;
243
}
244

245
// Common UI events
246
interface UIPluginEvents {
247
  'drag-over': (event: DragEvent) => void;
248
  'drag-leave': (event: DragEvent) => void;
249
  'file-input-change': (event: Event) => void;
250
}
251
```
252

253
## Common UI Options
254

255
```typescript { .api }
256
/**
257
 * Common options available across UI plugins
258
 */
259
interface CommonUIOptions {
260
  target?: string | Element;
261
  locale?: Locale;
262
  replaceTargetContent?: boolean;
263
}
264

265
/**
266
 * Styling options for UI plugins
267
 */
268
interface UIStyleOptions {
269
  width?: number | string;
270
  height?: number | string;
271
  theme?: 'light' | 'dark' | 'auto';
272
}
273

274
/**
275
 * Metadata field configuration for file editing
276
 */
277
interface MetaField {
278
  id: string;
279
  name: string;
280
  placeholder?: string;
281
  render?: (field: FieldRenderOptions, h: ComponentRender) => ComponentChild;
282
}
283

284
interface FieldRenderOptions {
285
  value: any;
286
  onChange: (value: any) => void;
287
  fieldCSSClasses: string[];
288
  required: boolean;
289
}
290
```