0
# Modal Management
1

2
Control dashboard visibility and interaction modes for overlay-style file selection interfaces.
3

4
## Capabilities
5

6
### Open Modal
7

8
Open the dashboard modal interface with optional animation and focus management.
9

10
```typescript { .api }
11
/**
12
 * Open the dashboard modal interface
13
 * Handles focus management, scroll prevention, and animations
14
 * @returns Promise that resolves when modal is fully opened
15
 */
16
openModal(): Promise<void>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import Dashboard from "@uppy/dashboard";
23

24
const dashboard = uppy.getPlugin("Dashboard") as Dashboard;
25

26
// Open modal programmatically
27
await dashboard.openModal();
28
console.log("Modal is now open");
29

30
// Open modal with user interaction
31
document.getElementById("upload-btn").addEventListener("click", async () => {
32
  await dashboard.openModal();
33
});
34
```
35

36
**Behavior:**
37
- Saves current scroll position and active element for restoration
38
- Applies `uppy-Dashboard-isFixed` class to body if `disablePageScrollWhenModalOpen` is true
39
- Handles animation if `animateOpenClose` is enabled
40
- Updates browser history if `browserBackButtonClose` is enabled
41
- Sets up keyboard event listeners for ESC and TAB keys
42
- Emits `dashboard:modal-open` event
43

44
### Close Modal
45

46
Close the dashboard modal with optional manual close flag and cleanup.
47

48
```typescript { .api }
49
/**
50
 * Close the dashboard modal with optional manual close flag
51
 * @param opts - Optional configuration for close behavior
52
 * @param opts.manualClose - Whether modal is being closed manually (default: true)
53
 * @returns Promise that resolves when modal is fully closed, or void if already closing
54
 */
55
closeModal(opts?: { manualClose: boolean }): void | Promise<void>;
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
// Close modal programmatically (manual close)
62
await dashboard.closeModal();
63

64
// Close modal automatically (non-manual close)
65
await dashboard.closeModal({ manualClose: false });
66

67
// Close modal on upload completion
68
uppy.on("complete", () => {
69
  if (dashboard.opts.closeAfterFinish) {
70
    dashboard.closeModal();
71
  }
72
});
73
```
74

75
**Behavior:**
76
- Returns early if modal is already hidden or closing
77
- Removes `uppy-Dashboard-isFixed` class from body if applicable
78
- Handles close animation if `animateOpenClose` is enabled
79
- Restores focus to previously active element
80
- Manages browser history cleanup if `browserBackButtonClose` is enabled
81
- Removes keyboard event listeners
82
- Emits `dashboard:modal-closed` event
83

84
### Check Modal State
85

86
Check if the dashboard modal is currently open.
87

88
```typescript { .api }
89
/**
90
 * Check if modal is currently open
91
 * @returns True if modal is open, false if hidden
92
 */
93
isModalOpen(): boolean;
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
// Check modal state
100
if (dashboard.isModalOpen()) {
101
  console.log("Modal is currently open");
102
} else {
103
  console.log("Modal is hidden");
104
}
105

106
// Conditional operations based on modal state
107
function handleFileSelection(files: File[]) {
108
  if (!dashboard.isModalOpen()) {
109
    await dashboard.openModal();
110
  }
111
  dashboard.addFiles(files);
112
}
113

114
// Toggle modal state
115
function toggleModal() {
116
  if (dashboard.isModalOpen()) {
117
    dashboard.closeModal();
118
  } else {
119
    dashboard.openModal();
120
  }
121
}
122
```
123

124
### Modal Configuration
125

126
Configuration options specific to modal behavior.
127

128
```typescript { .api }
129
/**
130
 * Modal-specific configuration options
131
 */
132
interface DashboardModalOptions {
133
  /** Indicates modal mode (default: false) */
134
  inline?: false;
135
  /** Enable open/close animations (default: true) */
136
  animateOpenClose?: boolean;
137
  /** Close modal with browser back button (default: false) */
138
  browserBackButtonClose?: boolean;
139
  /** Auto-close modal after upload completion (default: false) */
140
  closeAfterFinish?: boolean;
141
  /** Close modal when clicking outside (default: false) */
142
  closeModalOnClickOutside?: boolean;
143
  /** Disable page scroll when modal open (default: true) */
144
  disablePageScrollWhenModalOpen?: boolean;
145
}
146
```
147

148
**Configuration Examples:**
149

150
```typescript
151
// Modal with animations and browser back button support
152
uppy.use(Dashboard, {
153
  inline: false,
154
  animateOpenClose: true,
155
  browserBackButtonClose: true,
156
  closeModalOnClickOutside: true,
157
  closeAfterFinish: true
158
});
159

160
// Simple modal without animations
161
uppy.use(Dashboard, {
162
  inline: false,
163
  animateOpenClose: false,
164
  disablePageScrollWhenModalOpen: false
165
});
166
```
167

168
### Modal Events
169

170
Events emitted during modal lifecycle for integration and customization.
171

172
```typescript { .api }
173
/**
174
 * Modal-related events
175
 */
176
interface DashboardModalEvents {
177
  /** Emitted when modal opens */
178
  "dashboard:modal-open": () => void;
179
  /** Emitted when modal closes */
180
  "dashboard:modal-closed": () => void;
181
}
182
```
183

184
**Event Usage Examples:**
185

186
```typescript
187
// Listen for modal events
188
uppy.on("dashboard:modal-open", () => {
189
  console.log("Dashboard modal opened");
190
  // Track analytics, update UI state, etc.
191
});
192

193
uppy.on("dashboard:modal-closed", () => {
194
  console.log("Dashboard modal closed");
195
  // Cleanup, save state, etc.
196
});
197

198
// Conditional behavior based on modal events
199
uppy.on("dashboard:modal-open", () => {
200
  // Pause other UI animations
201
  document.body.classList.add("modal-active");
202
});
203

204
uppy.on("dashboard:modal-closed", () => {
205
  // Resume other UI animations
206
  document.body.classList.remove("modal-active");
207
});
208
```
209

210
### Trigger Configuration
211

212
Configure elements that can trigger modal opening.
213

214
```typescript { .api }
215
/**
216
 * Trigger configuration for modal opening
217
 */
218
interface DashboardTriggerConfig {
219
  /** Element/selector to trigger modal opening */
220
  trigger?: string | Element | null;
221
}
222
```
223

224
**Trigger Examples:**
225

226
```typescript
227
// Single element trigger
228
uppy.use(Dashboard, {
229
  trigger: "#upload-button"
230
});
231

232
// Multiple element triggers (CSS selector)
233
uppy.use(Dashboard, {
234
  trigger: ".upload-trigger"
235
});
236

237
// DOM element trigger
238
const uploadBtn = document.getElementById("upload-btn");
239
uppy.use(Dashboard, {
240
  trigger: uploadBtn
241
});
242

243
// No automatic trigger (manual control only)
244
uppy.use(Dashboard, {
245
  trigger: null
246
});
247
```
248

249
### Modal vs Inline Mode
250

251
Key differences between modal and inline dashboard modes.
252

253
```typescript { .api }
254
/**
255
 * Modal mode characteristics:
256
 * - Overlay display above page content
257
 * - Focus management and keyboard trapping
258
 * - Browser history integration option
259
 * - Page scroll prevention option
260
 * - Click-outside-to-close option
261
 * - Animation support for open/close
262
 */
263
interface ModalModeFeatures {
264
  overlay: boolean;
265
  focusManagement: boolean;
266
  historyIntegration: boolean;
267
  scrollPrevention: boolean;
268
  clickOutsideClose: boolean;
269
  animations: boolean;
270
}
271

272
/**
273
 * Inline mode characteristics:
274
 * - Embedded in page content
275
 * - No focus trapping (normal tab flow)
276
 * - No browser history changes
277
 * - Fixed dimensions (width/height)
278
 * - Always visible when mounted
279
 * - No open/close animations
280
 */
281
interface InlineModeFeatures {
282
  embedded: boolean;
283
  normalTabFlow: boolean;
284
  fixedDimensions: boolean;
285
  alwaysVisible: boolean;
286
}
287
```
288

289
**Mode Selection Examples:**
290

291
```typescript
292
// Modal mode for overlay file selection
293
uppy.use(Dashboard, {
294
  inline: false,
295
  target: "body",
296
  trigger: "#upload-button",
297
  animateOpenClose: true
298
});
299

300
// Inline mode for embedded file management
301
uppy.use(Dashboard, {
302
  inline: true,
303
  target: "#file-upload-area",
304
  width: "100%",
305
  height: 400
306
});
307
```