0
# TypeScript Support
1

2
Uppy provides comprehensive TypeScript definitions for all components, options, and events. The package includes full type safety with generic support for custom metadata and response body types.
3

4
## Capabilities
5

6
### Core Type Parameters
7

8
Uppy uses generic type parameters to provide type safety for custom metadata and response bodies.
9

10
```typescript { .api }
11
/**
12
 * Core generic type parameters used throughout Uppy
13
 */
14
interface Meta {
15
  [key: string]: any;
16
}
17

18
interface Body {
19
  [key: string]: any;
20
}
21

22
// Usage with custom types
23
interface MyMetadata {
24
  userId: string;
25
  projectId: string;
26
  tags: string[];
27
  caption?: string;
28
}
29

30
interface MyResponseBody {
31
  fileId: string;
32
  url: string;
33
  thumbnailUrl?: string;
34
}
35

36
const uppy = new Uppy<MyMetadata, MyResponseBody>({
37
  meta: {
38
    userId: 'user123',
39
    projectId: 'proj456',
40
    tags: ['work', 'important']
41
  }
42
});
43
```
44

45
### File Type Definitions
46

47
Complete type definitions for file objects and related interfaces.
48

49
```typescript { .api }
50
/**
51
 * Core file object with full type safety
52
 */
53
interface UppyFile<M extends Meta = {}, B extends Body = {}> {
54
  id: string;
55
  name: string;
56
  extension: string;
57
  meta: M & UppyFileMeta;
58
  type?: string;
59
  data: Blob | File;
60
  progress?: FileProgress;
61
  size: number;
62
  isGhost: boolean;
63
  source?: string;
64
  remote?: Remote;
65
  preview?: string;
66
}
67

68
interface UppyFileMeta {
69
  name: string;
70
  type?: string;
71
  relativePath?: string;
72
  [key: string]: any;
73
}
74

75
interface FileProgress {
76
  percentage: number;
77
  bytesUploaded: number;
78
  bytesTotal: number;
79
  uploadComplete: boolean;
80
  uploadStarted: number | null;
81
}
82

83
interface Remote {
84
  companionUrl: string;
85
  url: string;
86
  body?: { [key: string]: any };
87
  headers?: { [key: string]: string };
88
}
89
```
90

91
### State Type Definitions
92

93
Complete type definitions for Uppy's internal state management.
94

95
```typescript { .api }
96
/**
97
 * Core Uppy state interface
98
 */
99
interface State<M extends Meta = {}, B extends Body = {}> {
100
  files: { [fileId: string]: UppyFile<M, B> };
101
  currentUploads: { [uploadId: string]: CurrentUpload<M, B> };
102
  allowNewUpload: boolean;
103
  capabilities: Capabilities;
104
  totalProgress: number;
105
  meta: M;
106
  info: InfoObject | null;
107
  plugins: { [pluginId: string]: BasePlugin<any, any, any> };
108
}
109

110
interface CurrentUpload<M extends Meta = {}, B extends Body = {}> {
111
  fileIDs: string[];
112
  step: number;
113
  result?: UploadResult<M, B>;
114
}
115

116
interface Capabilities {
117
  individualCancellation?: boolean;
118
  uploadProgress?: boolean;
119
  editMetadata?: boolean;
120
  resumableUploads?: boolean;
121
}
122

123
interface InfoObject {
124
  message: string;
125
  type: 'info' | 'warning' | 'error' | 'success';
126
  details?: string;
127
}
128
```
129

130
### Event Type Definitions
131

132
Comprehensive event system with full type safety.
133

134
```typescript { .api }
135
/**
136
 * Complete event map with typed handlers
137
 */
138
interface UppyEventMap<M extends Meta = {}, B extends Body = {}> {
139
  // File management events
140
  'file-added': (file: UppyFile<M, B>) => void;
141
  'file-removed': (file: UppyFile<M, B>, reason?: string) => void;
142
  'files-added': (files: UppyFile<M, B>[]) => void;
143
  
144
  // Upload lifecycle events
145
  'upload': (data: { id: string; fileIDs: string[] }) => void;
146
  'upload-start': (data: { id: string; fileIDs: string[] }) => void;
147
  'upload-progress': (file: UppyFile<M, B>, progress: FileProgress) => void;
148
  'upload-success': (file: UppyFile<M, B>, response: UploadSuccessResponse<B>) => void;
149
  'upload-error': (file: UppyFile<M, B>, error: Error, response?: UploadErrorResponse<M, B>) => void;
150
  'upload-retry': (fileId: string) => void;
151
  'complete': (result: UploadResult<M, B>) => void;
152
  
153
  // State management events
154
  'state-update': (prev: State<M, B>, next: State<M, B>, patch: Partial<State<M, B>>) => void;
155
  'info-visible': () => void;
156
  'info-hidden': () => void;
157
  
158
  // Restriction and validation events
159
  'restriction-failed': (file: UppyFile<M, B>, error: Error) => void;
160
  'file-editor:cancel': (file?: UppyFile<M, B>) => void;
161
  'file-editor:complete': (file?: UppyFile<M, B>) => void;
162
  
163
  // Cancel events
164
  'cancel-all': () => void;
165
}
166

167
interface UploadResult<M extends Meta = {}, B extends Body = {}> {
168
  successful: UppyFile<M, B>[];
169
  failed: UppyFile<M, B>[];
170
  uploadID: string;
171
}
172

173
interface UploadSuccessResponse<B extends Body = {}> {
174
  status: number;
175
  body: B;
176
  uploadURL?: string;
177
}
178

179
interface UploadErrorResponse<M extends Meta = {}, B extends Body = {}> {
180
  status: number;
181
  body: any;
182
  message?: string;
183
  details?: string;
184
}
185
```
186

187
### Plugin Type Definitions
188

189
Type definitions for plugin development and configuration.
190

191
```typescript { .api }
192
/**
193
 * Plugin option types for all official plugins
194
 */
195
export type {
196
  // Core types
197
  UppyOptions, UIPluginOptions,
198
  
199
  // UI Plugin options
200
  DashboardOptions, DragDropOptions, FileInputOptions, DropTargetOptions,
201
  ProgressBarOptions, StatusBarOptions, InformerOptions,
202
  
203
  // File source options
204
  WebcamOptions, AudioOptions, ScreenCaptureOptions, 
205
  ImageEditorOptions, CompressorOptions,
206
  
207
  // Cloud provider options
208
  GoogleDriveOptions, DropboxOptions, BoxOptions, OneDriveOptions,
209
  InstagramOptions, FacebookOptions, UnsplashOptions, UrlOptions,
210
  RemoteSourcesOptions, ZoomOptions,
211
  
212
  // Upload handler options
213
  TusOptions, XHRUploadOptions, AwsS3Options, TransloaditOptions,
214
  
215
  // Utility plugin options
216
  ThumbnailGeneratorOptions, GoldenRetrieverOptions, FormOptions
217
};
218

219
/**
220
 * Plugin base class type definitions
221
 */
222
abstract class BasePlugin<Options = {}, State = {}, Events = {}> {
223
  readonly id: string;
224
  readonly type: string;
225
  readonly uppy: Uppy<any, any>;
226
  readonly opts: Options;
227
  
228
  constructor(uppy: Uppy<any, any>, options?: Options);
229
  
230
  abstract install(): void;
231
  abstract uninstall(): void;
232
  
233
  protected setOptions(newOptions: Partial<Options>): void;
234
  protected getPluginState(): State;
235
  protected setPluginState(patch: Partial<State>): void;
236
}
237

238
abstract class UIPlugin<Options = {}, State = {}> extends BasePlugin<Options, State> {
239
  protected render(): ComponentChild;
240
  protected mount(target: string | Element, plugin: UIPlugin<any, any>): void;
241
  protected unmount(): void;
242
  protected rerender(): void;
243
  protected getElement(): Element | null;
244
}
245
```
246

247
### Configuration Type Definitions
248

249
Complete type definitions for Uppy configuration options.
250

251
```typescript { .api }
252
/**
253
 * Core Uppy configuration options
254
 */
255
interface UppyOptions<M extends Meta = {}, B extends Body = {}> {
256
  id?: string;
257
  autoProceed?: boolean;
258
  allowMultipleUploads?: boolean;
259
  debug?: boolean;
260
  restrictions?: Restrictions;
261
  meta?: M;
262
  onBeforeFileAdded?: (
263
    currentFile: UppyFile<M, B>, 
264
    files: { [fileId: string]: UppyFile<M, B> }
265
  ) => UppyFile<M, B> | boolean | undefined;
266
  onBeforeUpload?: (
267
    files: { [fileId: string]: UppyFile<M, B> }
268
  ) => { [fileId: string]: UppyFile<M, B> } | boolean | undefined;
269
  locale?: Locale;
270
  store?: Store;
271
  logger?: Logger;
272
  infoTimeout?: number;
273
}
274

275
interface Restrictions {
276
  maxFileSize?: number | null;
277
  minFileSize?: number | null;
278
  maxTotalFileSize?: number | null;
279
  maxNumberOfFiles?: number | null;
280
  minNumberOfFiles?: number | null;
281
  allowedFileTypes?: string[] | null;
282
  requiredMetaFields?: string[];
283
}
284

285
interface Locale {
286
  strings: LocaleStrings;
287
  pluralize?: (count: number) => number;
288
}
289

290
interface LocaleStrings {
291
  [key: string]: string | LocaleStrings;
292
}
293

294
interface Store {
295
  getState(): any;
296
  setState(patch: any): void;
297
  subscribe(listener: () => void): () => void;
298
}
299

300
interface Logger {
301
  debug(...args: any[]): void;
302
  warn(...args: any[]): void;
303
  error(...args: any[]): void;
304
}
305
```
306

307
### Utility Type Helpers
308

309
Helper types for common TypeScript patterns in Uppy usage.
310

311
```typescript { .api }
312
/**
313
 * Utility types for common patterns
314
 */
315
type DeepPartial<T> = {
316
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
317
};
318

319
type PluginOptions<T> = T extends BasePlugin<infer Options, any, any> ? Options : never;
320

321
type FileWithMeta<M extends Meta> = UppyFile<M, any>;
322

323
type UploadHandler<M extends Meta, B extends Body> = (
324
  files: UppyFile<M, B>[],
325
  options: any
326
) => Promise<UploadResult<M, B>>;
327

328
/**
329
 * Plugin constructor type helper
330
 */
331
type PluginConstructor<Options = {}, State = {}> = {
332
  new (uppy: Uppy<any, any>, options?: Options): BasePlugin<Options, State>;
333
};
334

335
/**
336
 * Event handler type helper
337
 */
338
type EventHandler<T extends keyof UppyEventMap<any, any>> = UppyEventMap<any, any>[T];
339
```
340

341
### Advanced Usage Examples
342

343
Examples demonstrating advanced TypeScript usage patterns.
344

345
```typescript { .api }
346
/**
347
 * Advanced TypeScript usage examples
348
 */
349

350
// Custom metadata interface
351
interface ProjectMetadata {
352
  projectId: string;
353
  userId: string;
354
  department: 'engineering' | 'design' | 'marketing';
355
  tags: string[];
356
  priority: 'low' | 'medium' | 'high';
357
  dueDate?: Date;
358
}
359

360
// Custom response body interface  
361
interface UploadResponseBody {
362
  fileId: string;
363
  publicUrl: string;
364
  thumbnailUrl?: string;
365
  processingStatus: 'pending' | 'complete' | 'failed';
366
  metadata: {
367
    width?: number;
368
    height?: number;
369
    duration?: number;
370
  };
371
}
372

373
// Type-safe Uppy instance
374
const typedUppy = new Uppy<ProjectMetadata, UploadResponseBody>({
375
  debug: true,
376
  restrictions: {
377
    maxFileSize: 10 * 1024 * 1024,
378
    allowedFileTypes: ['image/*', 'video/*']
379
  },
380
  meta: {
381
    projectId: 'proj-123',
382
    userId: 'user-456', 
383
    department: 'engineering',
384
    tags: ['prototype', 'testing'],
385
    priority: 'high'
386
  },
387
  onBeforeFileAdded: (currentFile, files) => {
388
    // Type-safe file metadata access
389
    console.log('Adding file for project:', currentFile.meta.projectId);
390
    console.log('User department:', currentFile.meta.department);
391
    
392
    // Validation with full type safety
393
    if (currentFile.meta.priority === 'high' && Object.keys(files).length >= 5) {
394
      return false; // Reject file
395
    }
396
    
397
    return currentFile;
398
  }
399
});
400

401
// Type-safe event handlers
402
typedUppy.on('upload-success', (file, response) => {
403
  // Full type safety for custom metadata and response
404
  console.log(`File ${file.name} uploaded for project ${file.meta.projectId}`);
405
  console.log(`Available at: ${response.body.publicUrl}`);
406
  console.log(`Processing status: ${response.body.processingStatus}`);
407
  
408
  if (response.body.metadata.width && response.body.metadata.height) {
409
    console.log(`Image dimensions: ${response.body.metadata.width}x${response.body.metadata.height}`);
410
  }
411
});
412

413
// Type-safe plugin usage with custom options
414
interface CustomDashboardMeta extends ProjectMetadata {
415
  uploadReason: string;
416
}
417

418
typedUppy.use(Dashboard, {
419
  target: '#uppy-dashboard',
420
  metaFields: [
421
    { id: 'uploadReason', name: 'Upload Reason', placeholder: 'Why are you uploading this file?' },
422
    { id: 'priority', name: 'Priority' },
423
    { id: 'tags', name: 'Tags' }
424
  ] as MetaField[],
425
  onRequestCloseModal: () => {
426
    const files = typedUppy.getFiles();
427
    const hasHighPriority = files.some(file => file.meta.priority === 'high');
428
    
429
    if (hasHighPriority) {
430
      return confirm('You have high priority files. Are you sure you want to close?');
431
    }
432
    return true;
433
  }
434
});
435
```
436

437
## Type Declaration Files
438

439
```typescript { .api }
440
/**
441
 * Module declaration for CSS imports (when using bundlers)
442
 */
443
declare module "*.css" {
444
  const content: string;
445
  export default content;
446
}
447

448
/**
449
 * Global type augmentation for window object
450
 */
451
declare global {
452
  interface Window {
453
    Uppy?: typeof Uppy;
454
  }
455
}
456

457
/**
458
 * Preact component types for UI plugins
459
 */
460
type ComponentChild = any;
461
type ComponentRender = (type: any, props?: any, ...children: ComponentChild[]) => ComponentChild;
462
```