0
# Uppy
1

2
Uppy is a sleek, modular JavaScript file uploader that integrates seamlessly with any application. It provides a comprehensive ecosystem of plugins for file uploads with support for drag-and-drop, resumable uploads, previews, restrictions, file processing, and remote providers like Instagram, Dropbox, Google Drive, and S3.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import Uppy from "uppy";
15
// Or import specific components
16
import { Uppy, Dashboard, Tus, AwsS3 } from "uppy";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const Uppy = require("uppy");
23
// Or destructure specific exports
24
const { Uppy, Dashboard, Tus } = require("uppy");
25
```
26

27
## Basic Usage
28

29
```typescript
30
import { Uppy, Dashboard, Tus } from "uppy";
31

32
// Create Uppy instance with configuration
33
const uppy = new Uppy({
34
  debug: true,
35
  autoProceed: false,
36
  restrictions: {
37
    maxFileSize: 10 * 1024 * 1024, // 10MB
38
    maxNumberOfFiles: 5,
39
    allowedFileTypes: ['image/*', '.pdf']
40
  }
41
})
42
  .use(Dashboard, { 
43
    target: '#uppy-dashboard',
44
    inline: true,
45
    width: "100%",
46
    height: 400 
47
  })
48
  .use(Tus, { 
49
    endpoint: 'https://tusd.tusdemo.net/files/' 
50
  })
51
  .on('complete', (result) => {
52
    console.log('Upload complete:', result);
53
  });
54
```
55

56
## Architecture
57

58
Uppy is built around several key architectural components:
59

60
- **Core Uppy Class**: Central orchestrator managing files, state, plugins, and upload lifecycle
61
- **Plugin System**: Modular architecture with 31+ official plugins for UI, file sources, uploaders, and utilities
62
- **Plugin Base Classes**: `BasePlugin` and `UIPlugin` providing foundation for custom plugins
63
- **State Management**: Centralized state with configurable stores (default or Redux)
64
- **Event System**: Comprehensive event emission for upload lifecycle, file management, and plugin interactions
65
- **File Management**: Complete file object handling with metadata, restrictions, and validation
66
- **Upload Protocols**: Support for multiple protocols including tus (resumable), XHR, and S3 direct upload
67

68
## Capabilities
69

70
### Core Uppy Class
71

72
Central Uppy class providing file management, upload control, plugin system, and state management with comprehensive event handling.
73

74
```typescript { .api }
75
class Uppy<M extends Meta = {}, B extends Body = {}> {
76
  constructor(options?: UppyOptions<M, B>);
77
  
78
  // File management
79
  addFile(file: UppyFile<M, B> | AddFileOptions<M, B>): string;
80
  addFiles(files: (UppyFile<M, B> | AddFileOptions<M, B>)[]): void;
81
  removeFile(fileId: string): void;
82
  removeFiles(fileIds?: string[]): void;
83
  getFile(fileId: string): UppyFile<M, B> | undefined;
84
  getFiles(): UppyFile<M, B>[];
85
  
86
  // Upload control
87
  upload(): Promise<UploadResult<M, B>>;
88
  pauseAll(): void;
89
  resumeAll(): void;
90
  retryAll(): Promise<UploadResult<M, B>>;
91
  retryUpload(fileId: string): Promise<UploadResult<M, B>>;
92
  cancelAll(): void;
93
  
94
  // Plugin management
95
  use<T extends BasePlugin<any, any, any>>(plugin: T, options?: T extends BasePlugin<infer Options, any, any> ? Options : never): this;
96
  removePlugin(instance: BasePlugin<any, any, any>): void;
97
  getPlugin<T extends BasePlugin<any, any, any>>(id: string): T | undefined;
98
  
99
  // State management
100
  getState(): State<M, B>;
101
  setState(patch: Partial<State<M, B>>): void;
102
  setMeta(data: Partial<M>): void;
103
  setFileMeta(fileId: string, data: Partial<M>): void;
104
  
105
  // Event system
106
  on<K extends keyof UppyEventMap<M, B>>(event: K, callback: UppyEventMap<M, B>[K]): this;
107
  off<K extends keyof UppyEventMap<M, B>>(event: K, callback: UppyEventMap<M, B>[K]): this;
108
  emit<K extends keyof UppyEventMap<M, B>>(event: K, ...args: Parameters<UppyEventMap<M, B>[K]>): void;
109
}
110
```
111

112
[Core Uppy Class](./core-uppy.md)
113

114
### UI Plugins
115

116
Comprehensive collection of user interface plugins for file input, display, and interaction.
117

118
```typescript { .api }
119
// Dashboard - Primary UI with full feature set
120
class Dashboard<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DashboardOptions<M, B>>;
121

122
// File Input Components
123
class DragDrop<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DragDropOptions>;
124
class FileInput<M extends Meta = {}, B extends Body = {}> extends UIPlugin<FileInputOptions>;
125
class DropTarget<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DropTargetOptions>;
126

127
// Progress Display
128
class ProgressBar<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ProgressBarOptions>;
129
class StatusBar<M extends Meta = {}, B extends Body = {}> extends UIPlugin<StatusBarOptions<M, B>>;
130
class Informer<M extends Meta = {}, B extends Body = {}> extends UIPlugin<InformerOptions>;
131
```
132

133
[UI Plugins](./ui-plugins.md)
134

135
### File Sources
136

137
Plugins for acquiring files from various sources including local devices, cameras, and recording capabilities.
138

139
```typescript { .api }
140
// Media Capture
141
class Webcam<M extends Meta = {}, B extends Body = {}> extends UIPlugin<WebcamOptions>;
142
class Audio<M extends Meta = {}, B extends Body = {}> extends UIPlugin<AudioOptions>;
143
class ScreenCapture<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ScreenCaptureOptions>;
144

145
// File Processing
146
class ImageEditor<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ImageEditorOptions>;
147
class Compressor<M extends Meta = {}, B extends Body = {}> extends BasePlugin<CompressorOptions>;
148
```
149

150
[File Sources](./file-sources.md)
151

152
### Cloud Providers
153

154
Remote file source plugins enabling import from popular cloud storage and social media services.
155

156
```typescript { .api }
157
// Cloud Storage
158
class GoogleDrive<M extends Meta = {}, B extends Body = {}> extends BasePlugin<GoogleDriveOptions>;
159
class GoogleDrivePicker<M extends Meta = {}, B extends Body = {}> extends UIPlugin<GoogleDrivePickerOptions>;
160
class Dropbox<M extends Meta = {}, B extends Body = {}> extends BasePlugin<DropboxOptions>;
161
class Box<M extends Meta = {}, B extends Body = {}> extends BasePlugin<BoxOptions>;
162
class OneDrive<M extends Meta = {}, B extends Body = {}> extends BasePlugin<OneDriveOptions>;
163

164
// Social Media
165
class Instagram<M extends Meta = {}, B extends Body = {}> extends BasePlugin<InstagramOptions>;
166
class Facebook<M extends Meta = {}, B extends Body = {}> extends BasePlugin<FacebookOptions>;
167
class Unsplash<M extends Meta = {}, B extends Body = {}> extends BasePlugin<UnsplashOptions>;
168
```
169

170
[Cloud Providers](./cloud-providers.md)
171

172
### Upload Handlers
173

174
Plugins handling the actual file upload process with support for various protocols and destinations.
175

176
```typescript { .api }
177
// Upload Protocols
178
class Tus<M extends Meta = {}, B extends Body = {}> extends BasePlugin<TusOptions>;
179
class XHRUpload<M extends Meta = {}, B extends Body = {}> extends BasePlugin<XHRUploadOptions<M, B>>;
180
class AwsS3<M extends Meta = {}, B extends Body = {}> extends BasePlugin<AwsS3Options>;
181

182
// Processing Services  
183
class Transloadit<M extends Meta = {}, B extends Body = {}> extends BasePlugin<TransloaditOptions>;
184
```
185

186
[Upload Handlers](./upload-handlers.md)
187

188
### Utility Plugins
189

190
Supporting plugins providing additional functionality like thumbnail generation, crash recovery, and form integration.
191

192
```typescript { .api }
193
// File Processing
194
class ThumbnailGenerator<M extends Meta = {}, B extends Body = {}> extends BasePlugin<ThumbnailGeneratorOptions>;
195

196
// State Management
197
class GoldenRetriever<M extends Meta = {}, B extends Body = {}> extends BasePlugin<GoldenRetrieverOptions>;
198
class Form<M extends Meta = {}, B extends Body = {}> extends BasePlugin<FormOptions>;
199

200
// Development Tools
201
class ReduxDevTools<M extends Meta = {}, B extends Body = {}> extends BasePlugin<any>;
202
```
203

204
[Utility Plugins](./utility-plugins.md)
205

206
### Plugin Architecture
207

208
Base classes and architecture for creating custom plugins and extending Uppy functionality.
209

210
```typescript { .api }
211
abstract class BasePlugin<Options, State = {}, Events = {}> {
212
  constructor(uppy: Uppy<any, any>, options?: Options);
213
  
214
  abstract install(): void;
215
  abstract uninstall(): void;
216
  
217
  // Plugin lifecycle
218
  protected setOptions(newOptions: Partial<Options>): void;
219
  protected getPluginState(): State;
220
  protected setPluginState(patch: Partial<State>): void;
221
}
222

223
abstract class UIPlugin<Options, State = {}> extends BasePlugin<Options, State> {
224
  protected render(): ComponentChild;
225
  protected mount(target: string | Element, plugin: UIPlugin<any, any>): void;
226
  protected unmount(): void;
227
}
228
```
229

230
[Plugin Architecture](./plugin-architecture.md)
231

232
### TypeScript Support
233

234
Comprehensive TypeScript definitions for all Uppy components, options, and events.
235

236
```typescript { .api }
237
// Core types
238
interface UppyOptions<M extends Meta = {}, B extends Body = {}> {
239
  id?: string;
240
  autoProceed?: boolean;
241
  allowMultipleUploads?: boolean;
242
  debug?: boolean;
243
  restrictions?: Restrictions;
244
  meta?: M;
245
  onBeforeFileAdded?: (currentFile: UppyFile<M, B>, files: { [fileId: string]: UppyFile<M, B> }) => UppyFile<M, B> | boolean | undefined;
246
  onBeforeUpload?: (files: { [fileId: string]: UppyFile<M, B> }) => { [fileId: string]: UppyFile<M, B> } | boolean | undefined;
247
  locale?: Locale;
248
  store?: Store;
249
  logger?: Logger;
250
  infoTimeout?: number;
251
}
252

253
// File types
254
interface UppyFile<M extends Meta = {}, B extends Body = {}> {
255
  id: string;
256
  name: string;
257
  extension: string;
258
  meta: M & UppyFileMeta;
259
  type?: string;
260
  data: Blob | File;
261
  progress?: FileProgress;
262
  size: number;
263
  isGhost: boolean;
264
  source?: string;
265
  remote?: Remote;
266
  preview?: string;
267
}
268

269
// Event system
270
interface UppyEventMap<M extends Meta = {}, B extends Body = {}> {
271
  'file-added': (file: UppyFile<M, B>) => void;
272
  'file-removed': (file: UppyFile<M, B>, reason?: string) => void;
273
  'upload': (data: { id: string; fileIDs: string[] }) => void;
274
  'upload-progress': (file: UppyFile<M, B>, progress: FileProgress) => void;
275
  'upload-success': (file: UppyFile<M, B>, response: UploadSuccessResponse<B>) => void;
276
  'complete': (result: UploadResult<M, B>) => void;
277
  // ... additional events
278
}
279
```
280

281
[TypeScript Support](./typescript-support.md)
282

283
## Core Types
284

285
```typescript { .api }
286
interface State<M extends Meta = {}, B extends Body = {}> {
287
  files: { [fileId: string]: UppyFile<M, B> };
288
  currentUploads: { [uploadId: string]: CurrentUpload<M, B> };
289
  allowNewUpload: boolean;
290
  capabilities: Capabilities;
291
  totalProgress: number;
292
  meta: M;
293
  info: InfoObject | null;
294
  plugins: { [pluginId: string]: BasePlugin<any, any, any> };
295
}
296

297
interface Meta {
298
  [key: string]: any;
299
}
300

301
interface Body {
302
  [key: string]: any;
303
}
304

305
interface Restrictions {
306
  maxFileSize?: number | null;
307
  minFileSize?: number | null;
308
  maxTotalFileSize?: number | null;
309
  maxNumberOfFiles?: number | null;
310
  minNumberOfFiles?: number | null;
311
  allowedFileTypes?: string[] | null;
312
  requiredMetaFields?: string[];
313
}
314

315
interface FileProgress {
316
  percentage: number;
317
  bytesUploaded: number;
318
  bytesTotal: number;
319
  uploadComplete: boolean;
320
  uploadStarted: number | null;
321
}
322

323
interface UploadResult<M extends Meta = {}, B extends Body = {}> {
324
  successful: UppyFile<M, B>[];
325
  failed: UppyFile<M, B>[];
326
  uploadID: string;
327
}
328
```