0
# Core Uppy Class
1

2
The Uppy class is the central component of the Uppy ecosystem, providing complete file upload management, state handling, plugin orchestration, and event coordination.
3

4
## Constructor
5

6
```typescript { .api }
7
constructor(opts?: UppyOptions<M, B>)
8
```
9

10
### Constructor Options
11

12
```typescript { .api }
13
interface UppyOptions<M extends Meta = Meta, B extends Body = Body> {
14
  id?: string;                     // Instance identifier (default: 'uppy')
15
  autoProceed?: boolean;           // Auto-start uploads (default: false)
16
  allowMultipleUploadBatches?: boolean; // Allow multiple batches (default: true)
17
  debug?: boolean;                 // Enable debug logging (default: false)
18
  restrictions?: Partial<Restrictions>; // File restrictions
19
  meta?: Partial<M>;              // Default file metadata
20
  locale?: Locale;                // Localization settings
21
  store?: Store;                  // Custom state store
22
  logger?: typeof debugLogger;    // Custom logger
23
  infoTimeout?: number;           // Info message duration (default: 5000ms)
24
  onBeforeFileAdded?: (
25
    currentFile: UppyFile<M, B>,
26
    files: { [key: string]: UppyFile<M, B> }
27
  ) => boolean | Promise<boolean>;
28
  onBeforeUpload?: (
29
    files: { [key: string]: UppyFile<M, B> }
30
  ) => boolean | Promise<boolean>;
31
}
32
```
33

34
## Static Properties
35

36
```typescript { .api }
37
static VERSION: string;  // Package version
38
```
39

40
## State Management
41

42
### Get and Set State
43

44
```typescript { .api }
45
getState(): State<M, B>;
46
setState(patch?: Partial<State<M, B>>): void;
47
```
48

49
### File-Specific State Updates
50

51
```typescript { .api }
52
setFileState(fileID: string, state: Partial<UppyFile<M, B>>): void;
53
patchFilesState(filesWithNewState: {
54
  [id: string]: Partial<UppyFile<M, B>>
55
}): void;
56
```
57

58
### Options Updates
59

60
```typescript { .api }
61
setOptions(newOpts: Partial<UppyOptions<M, B>>): void;
62
```
63

64
## File Management
65

66
### Adding Files
67

68
```typescript { .api }
69
addFile(file: File | MinimalRequiredUppyFile<M, B>): string;
70
addFiles(fileDescriptors: MinimalRequiredUppyFile<M, B>[]): void;
71
```
72

73
**Parameters:**
74
- `file`: Browser File object or minimal file descriptor
75
- `fileDescriptors`: Array of file descriptors
76

77
**Returns:** `addFile` returns the generated file ID
78

79
### Removing Files
80

81
```typescript { .api }
82
removeFile(fileID: string): void;
83
removeFiles(fileIDs: string[]): void;
84
```
85

86
### Retrieving Files
87

88
```typescript { .api }
89
getFile(fileID: string): UppyFile<M, B>;
90
getFiles(): UppyFile<M, B>[];
91
getFilesByIds(ids: string[]): UppyFile<M, B>[];
92
getObjectOfFilesPerState(): {
93
  newFiles: UppyFile<M, B>[];
94
  startedFiles: UppyFile<M, B>[];
95
  uploadStartedFiles: UppyFile<M, B>[];
96
  pausedFiles: UppyFile<M, B>[];
97
  completeFiles: UppyFile<M, B>[];
98
  erroredFiles: UppyFile<M, B>[];
99
  inProgressFiles: UppyFile<M, B>[];
100
  inProgressNotPausedFiles: UppyFile<M, B>[];
101
  processingFiles: UppyFile<M, B>[];
102
  isUploadStarted: boolean;
103
  isAllComplete: boolean;
104
  isAllErrored: boolean;
105
  isAllPaused: boolean;
106
  isUploadInProgress: boolean;
107
  isSomeGhost: boolean;
108
};
109
```
110

111
### File Existence Check
112

113
```typescript { .api }
114
checkIfFileAlreadyExists(fileID: string): boolean;
115
```
116

117
## Upload Control
118

119
### Starting Uploads
120

121
```typescript { .api }
122
upload(): Promise<UploadResult<M, B> | undefined>;
123
```
124

125
**Returns:** Promise resolving to upload result with successful/failed file counts and file data
126

127
### Pause and Resume
128

129
```typescript { .api }
130
pauseResume(fileID: string): boolean | undefined;
131
pauseAll(): void;
132
resumeAll(): void;
133
```
134

135
**Parameters:**
136
- `fileID`: Specific file to pause/resume
137

138
**Returns:** `pauseResume` returns the new paused state (true/false) or undefined if file not found
139

140
### Retry Operations
141

142
```typescript { .api }
143
retryAll(): Promise<UploadResult<M, B> | undefined>;
144
retryUpload(fileID: string): Promise<UploadResult<M, B> | undefined>;
145
```
146

147
### Cancel Operations
148

149
```typescript { .api }
150
cancelAll(): void;
151
```
152

153
## Event System
154

155
### Event Subscription
156

157
```typescript { .api }
158
on<K extends keyof UppyEventMap<M, B>>(
159
  event: K,
160
  callback: UppyEventMap<M, B>[K]
161
): this;
162

163
once<K extends keyof UppyEventMap<M, B>>(
164
  event: K,
165
  callback: UppyEventMap<M, B>[K]
166
): this;
167

168
off<K extends keyof UppyEventMap<M, B>>(
169
  event: K,
170
  callback: UppyEventMap<M, B>[K]
171
): this;
172
```
173

174
### Event Emission
175

176
```typescript { .api }
177
emit<K extends keyof UppyEventMap<M, B>>(
178
  event: K,
179
  ...args: Parameters<UppyEventMap<M, B>[K]>
180
): void;
181
```
182

183
## Validation
184

185
### File Validation
186

187
```typescript { .api }
188
validateRestrictions(
189
  file: ValidateableFile<M, B>,
190
  files?: ValidateableFile<M, B>[]
191
): RestrictionError<M, B> | null;
192

193
validateSingleFile(file: ValidateableFile<M, B>): string | null;
194
validateAggregateRestrictions(
195
  files: ValidateableFile<M, B>[]
196
): string | null;
197
```
198

199
**Parameters:**
200
- `file`: File to validate
201
- `files`: All files for aggregate validation
202

203
**Returns:** Error object/message if validation fails, null if valid
204

205
## Metadata Management
206

207
### Global Metadata
208

209
```typescript { .api }
210
setMeta(data: Partial<M>): void;
211
```
212

213
### File-Specific Metadata
214

215
```typescript { .api }
216
setFileMeta(fileID: string, data: Partial<M>): void;
217
```
218

219
## Plugin Management
220

221
### Plugin Installation
222

223
```typescript { .api }
224
use<T extends typeof BasePlugin<any, M, B>>(
225
  Plugin: T,
226
  ...args: OmitFirstArg<ConstructorParameters<T>>
227
): this;
228
```
229

230
### Plugin Access
231

232
```typescript { .api }
233
getPlugin<T extends UnknownPlugin<M, B> = UnknownPlugin<M, B>>(
234
  id: string
235
): T | undefined;
236
iteratePlugins(method: (plugin: UnknownPlugin<M, B>) => void): void;
237
```
238

239
### Plugin Removal
240

241
```typescript { .api }
242
removePlugin(instance: UnknownPlugin<M, B>): void;
243
```
244

245
## Processing Pipeline
246

247
### Preprocessors
248

249
```typescript { .api }
250
addPreProcessor(fn: Processor): void;
251
removePreProcessor(fn: Processor): boolean;
252
```
253

254
### Uploaders
255

256
```typescript { .api }
257
addUploader(fn: Processor): void;
258
removeUploader(fn: Processor): boolean;
259
```
260

261
### Postprocessors
262

263
```typescript { .api }
264
addPostProcessor(fn: Processor): void;
265
removePostProcessor(fn: Processor): boolean;
266
```
267

268
**Processor Type:**
269
```typescript { .api }
270
type Processor = (
271
  fileIDs: string[],
272
  uploadID: string
273
) => Promise<unknown> | void;
274
```
275

276
## Utility Methods
277

278
### Instance Management
279

280
```typescript { .api }
281
getID(): string;
282
clear(): void;
283
resetProgress(): void;
284
destroy(): void;
285
```
286

287
### Upload State Management
288

289
```typescript { .api }
290
restore(uploadID: string): Promise<UploadResult<M, B> | undefined>;
291
addResultData(uploadID: string, data: any): void;
292
```
293

294
### Remote File Support
295

296
```typescript { .api }
297
registerRequestClient(id: string, client: unknown): void;
298
getRequestClientForFile<Client>(file: UppyFile<M, B>): Client;
299
logout(): void;
300
```
301

302
### User Communication
303

304
```typescript { .api }
305
info(
306
  message: string | { message: string; details: string },
307
  type?: 'info' | 'warning' | 'error' | 'success',
308
  duration?: number
309
): void;
310
hideInfo(): void;
311
log(message: unknown, type?: 'error' | 'warning'): void;
312
```
313

314
### Network Status
315

316
```typescript { .api }
317
updateOnlineStatus(): void;
318
```
319

320
## Public Properties
321

322
```typescript { .api }
323
opts: UppyOptions<M, B>;           // Current options
324
store: Store;                      // State store instance
325
locale: Locale;                    // Current locale
326
i18n: I18n;                       // Translation function
327
i18nArray: Translator['translateArray']; // Array translation
328
```
329

330
## Usage Examples
331

332
### Basic File Upload
333

334
```typescript
335
import Uppy from '@uppy/core';
336

337
const uppy = new Uppy({
338
  restrictions: {
339
    maxFileSize: 5 * 1024 * 1024, // 5MB
340
    allowedFileTypes: ['image/*']
341
  }
342
});
343

344
// Add event listeners
345
uppy.on('file-added', (file) => {
346
  console.log('File added:', file.name);
347
});
348

349
uppy.on('upload-success', (file, response) => {
350
  console.log('Upload successful:', file.name, response);
351
});
352

353
// Add files and upload
354
const fileInput = document.querySelector('#file-input');
355
fileInput.addEventListener('change', (event) => {
356
  const files = Array.from(event.target.files);
357
  files.forEach(file => uppy.addFile(file));
358
  uppy.upload();
359
});
360
```
361

362
### Custom Validation
363

364
```typescript
365
const uppy = new Uppy({
366
  onBeforeFileAdded: (currentFile, files) => {
367
    // Custom validation logic
368
    if (currentFile.name.includes('temp')) {
369
      uppy.info('Temporary files are not allowed', 'error');
370
      return false;
371
    }
372
    return true;
373
  },
374
  onBeforeUpload: (files) => {
375
    // Pre-upload validation
376
    const fileCount = Object.keys(files).length;
377
    if (fileCount === 0) {
378
      uppy.info('Please select at least one file', 'error');
379
      return false;
380
    }
381
    return true;
382
  }
383
});
384
```
385

386
### Plugin Integration
387

388
```typescript
389
import Uppy from '@uppy/core';
390
import Dashboard from '@uppy/dashboard';
391
import XHRUpload from '@uppy/xhr-upload';
392

393
const uppy = new Uppy()
394
  .use(Dashboard, {
395
    target: '#uppy-dashboard',
396
    inline: true
397
  })
398
  .use(XHRUpload, {
399
    endpoint: '/upload',
400
    headers: {
401
      'Authorization': 'Bearer token'
402
    }
403
  });
404
```