0
# @uppy/dashboard
1

2
@uppy/dashboard is a universal UI plugin for Uppy that provides a comprehensive dashboard interface for file upload management. It offers drag-and-drop functionality, file previews, metadata editing, progress tracking, and seamless integration with remote storage providers through optional plugins.
3

4
## Package Information
5

6
- **Package Name**: @uppy/dashboard
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @uppy/dashboard`
10

11
## Core Imports
12

13
```typescript
14
import Dashboard from "@uppy/dashboard";
15
import type { DashboardOptions } from "@uppy/dashboard";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Dashboard = require("@uppy/dashboard");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import Uppy from "@uppy/core";
28
import Dashboard from "@uppy/dashboard";
29

30
// Create Uppy instance
31
const uppy = new Uppy();
32

33
// Add Dashboard plugin
34
uppy.use(Dashboard, {
35
  target: "#uppy-dashboard",
36
  inline: true,
37
  width: 750,
38
  height: 550,
39
  showProgressDetails: true,
40
  hideUploadButton: false,
41
  theme: "light"
42
});
43
```
44

45
## Architecture
46

47
@uppy/dashboard is built around several key components:
48

49
- **Dashboard Class**: Main plugin extending UIPlugin from @uppy/core
50
- **Modal/Inline Modes**: Supports both overlay modal and embedded inline display
51
- **Plugin Integration**: Automatic discovery and mounting of acquirer, editor, and progress indicator plugins
52
- **State Management**: Comprehensive state tracking for UI elements, files, and user interactions
53
- **Event System**: Rich event emission for customization and integration hooks
54
- **Theme System**: Support for light, dark, and auto themes with system preference detection
55

56
## Capabilities
57

58
### Modal Management
59

60
Control dashboard visibility and interaction modes for overlay-style file selection interfaces.
61

62
```typescript { .api }
63
interface Dashboard {
64
  /** Open the dashboard modal interface */
65
  openModal(): Promise<void>;
66
  /** Close the dashboard modal with optional manual close flag */
67
  closeModal(opts?: { manualClose: boolean }): void | Promise<void>;
68
  /** Check if modal is currently open */
69
  isModalOpen(): boolean;
70
}
71
```
72

73
[Modal Management](./modal-management.md)
74

75
### Panel Management
76

77
Manage visibility and state of plugin panels within the dashboard interface.
78

79
```typescript { .api }
80
interface Dashboard {
81
  /** Show specific plugin panel by ID */
82
  showPanel(id: string): void;
83
  /** Hide all currently open panels */
84
  hideAllPanels(): void;
85
}
86
```
87

88
[Panel Management](./panel-management.md)
89

90
### File Management
91

92
Handle file selection, metadata editing, and file operations within the dashboard.
93

94
```typescript { .api }
95
interface Dashboard {
96
  /** Add files to the uploader */
97
  addFiles(files: File[]): void;
98
  /** Save file metadata */
99
  saveFileCard(meta: Meta, fileID: string): void;
100
}
101
```
102

103
[File Management](./file-management.md)
104

105
### File Editor Integration
106

107
Integrate with file editor plugins for image editing and metadata management.
108

109
```typescript { .api }
110
interface Dashboard {
111
  /** Open file editor for specific file */
112
  openFileEditor(file: UppyFile): void;
113
  /** Close file editor panel */
114
  closeFileEditor(): void;
115
  /** Save file editor changes */
116
  saveFileEditor(): void;
117
}
118
```
119

120
[File Editor Integration](./file-editor.md)
121

122
### Plugin Target Management
123

124
Register and manage plugins that integrate with the dashboard interface.
125

126
```typescript { .api }
127
interface Dashboard {
128
  /** Register plugin as dashboard target */
129
  addTarget(plugin: UnknownPlugin): HTMLElement | null;
130
  /** Unregister plugin target */
131
  removeTarget(plugin: UnknownPlugin): void;
132
}
133
```
134

135
[Plugin Integration](./plugin-integration.md)
136

137
### Configuration Management
138

139
Configure dashboard appearance, behavior, and feature availability.
140

141
```typescript { .api }
142
interface Dashboard {
143
  /** Update dashboard options */
144
  setOptions(opts: Partial<DashboardOptions>): void;
145
  /** Set dark mode capability */
146
  setDarkModeCapability(isDarkModeOn: boolean): void;
147
}
148

149
type DashboardOptions<M extends Meta, B extends Body> = 
150
  DashboardMiscOptions<M, B> & 
151
  (DashboardModalOptions | DashboardInlineOptions);
152
```
153

154
[Configuration](./configuration.md)
155

156
## Dashboard Class
157

158
```typescript { .api }
159
/** Main Dashboard class extending UIPlugin */
160
class Dashboard<M extends Meta, B extends Body> extends UIPlugin {
161
  /** Package version string */
162
  static VERSION: string;
163
  
164
  /** Check if file can be edited with available editor plugins */
165
  canEditFile(file: UppyFile<M, B>): boolean;
166
}
167
```
168

169
## Global Types
170

171
```typescript { .api }
172
/** Dashboard state interface */
173
interface DashboardState<M extends Meta, B extends Body> {
174
  targets: Target[];
175
  activePickerPanel: Target | undefined;
176
  showAddFilesPanel: boolean;
177
  activeOverlayType: string | null;
178
  fileCardFor: string | null;
179
  showFileEditor: boolean;
180
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
181
  isHidden: boolean;
182
  isClosing: boolean;
183
  containerWidth: number;
184
  containerHeight: number;
185
  areInsidesReadyToBeVisible: boolean;
186
  isDraggingOver: boolean;
187
  [key: string]: unknown;
188
}
189

190
/** Plugin target interface */
191
interface Target {
192
  id: string;
193
  name: string;
194
  type: string;
195
}
196

197
/** Target with render capabilities */
198
interface TargetWithRender extends Target {
199
  icon: () => ComponentChild;
200
  render: () => ComponentChild;
201
}
202

203
/** Metadata field configuration */
204
interface MetaField {
205
  id: string;
206
  name: string;
207
  placeholder?: string;
208
  render?: (field: FieldRenderOptions, h: PreactRender) => VNode<any>;
209
}
210

211
/** Field render options */
212
interface FieldRenderOptions {
213
  value: string;
214
  onChange: (newVal: string) => void;
215
  fieldCSSClasses: { text: string };
216
  required: boolean;
217
  form: string;
218
}
219
```
220

221
## CSS Integration
222

223
@uppy/dashboard includes comprehensive CSS styling:
224

225
```typescript
226
// ES6 imports
227
import "@uppy/dashboard/dist/style.css";
228
// or minified version
229
import "@uppy/dashboard/dist/style.min.css";
230
```
231

232
Alternative import paths (from package.json exports):
233

234
```typescript
235
// Using package.json exports
236
import "@uppy/dashboard/css/style.css";
237
import "@uppy/dashboard/css/style.min.css";
238
```
239

240
HTML link tags:
241

242
```html
243
<!-- CDN -->
244
<link rel="stylesheet" href="https://releases.transloadit.com/uppy/v5.0.1/uppy.min.css">
245

246
<!-- Local file -->
247
<link rel="stylesheet" href="node_modules/@uppy/dashboard/dist/style.min.css">
248
```
249

250
CSS-in-JS frameworks:
251

252
```javascript
253
// Next.js
254
import "@uppy/dashboard/dist/style.css";
255

256
// Webpack
257
require("@uppy/dashboard/dist/style.css");
258
```