or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cloud-providers.mdcore-uppy.mdfile-sources.mdindex.mdplugin-architecture.mdtypescript-support.mdui-plugins.mdupload-handlers.mdutility-plugins.md
tile.json

tessl/npm-uppy

Extensible JavaScript file upload widget with support for drag&drop, resumable uploads, previews, restrictions, file processing/encoding, remote providers like Instagram, Dropbox, Google Drive, S3 and more.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/uppy@4.18.x

To install, run

npx @tessl/cli install tessl/npm-uppy@4.18.0

index.mddocs/

Uppy

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.

Package Information

  • Package Name: uppy
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install uppy

Core Imports

import Uppy from "uppy";
// Or import specific components
import { Uppy, Dashboard, Tus, AwsS3 } from "uppy";

For CommonJS:

const Uppy = require("uppy");
// Or destructure specific exports
const { Uppy, Dashboard, Tus } = require("uppy");

Basic Usage

import { Uppy, Dashboard, Tus } from "uppy";

// Create Uppy instance with configuration
const uppy = new Uppy({
  debug: true,
  autoProceed: false,
  restrictions: {
    maxFileSize: 10 * 1024 * 1024, // 10MB
    maxNumberOfFiles: 5,
    allowedFileTypes: ['image/*', '.pdf']
  }
})
  .use(Dashboard, { 
    target: '#uppy-dashboard',
    inline: true,
    width: "100%",
    height: 400 
  })
  .use(Tus, { 
    endpoint: 'https://tusd.tusdemo.net/files/' 
  })
  .on('complete', (result) => {
    console.log('Upload complete:', result);
  });

Architecture

Uppy is built around several key architectural components:

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

Capabilities

Core Uppy Class

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

class Uppy<M extends Meta = {}, B extends Body = {}> {
  constructor(options?: UppyOptions<M, B>);
  
  // File management
  addFile(file: UppyFile<M, B> | AddFileOptions<M, B>): string;
  addFiles(files: (UppyFile<M, B> | AddFileOptions<M, B>)[]): void;
  removeFile(fileId: string): void;
  removeFiles(fileIds?: string[]): void;
  getFile(fileId: string): UppyFile<M, B> | undefined;
  getFiles(): UppyFile<M, B>[];
  
  // Upload control
  upload(): Promise<UploadResult<M, B>>;
  pauseAll(): void;
  resumeAll(): void;
  retryAll(): Promise<UploadResult<M, B>>;
  retryUpload(fileId: string): Promise<UploadResult<M, B>>;
  cancelAll(): void;
  
  // Plugin management
  use<T extends BasePlugin<any, any, any>>(plugin: T, options?: T extends BasePlugin<infer Options, any, any> ? Options : never): this;
  removePlugin(instance: BasePlugin<any, any, any>): void;
  getPlugin<T extends BasePlugin<any, any, any>>(id: string): T | undefined;
  
  // State management
  getState(): State<M, B>;
  setState(patch: Partial<State<M, B>>): void;
  setMeta(data: Partial<M>): void;
  setFileMeta(fileId: string, data: Partial<M>): void;
  
  // Event system
  on<K extends keyof UppyEventMap<M, B>>(event: K, callback: UppyEventMap<M, B>[K]): this;
  off<K extends keyof UppyEventMap<M, B>>(event: K, callback: UppyEventMap<M, B>[K]): this;
  emit<K extends keyof UppyEventMap<M, B>>(event: K, ...args: Parameters<UppyEventMap<M, B>[K]>): void;
}

Core Uppy Class

UI Plugins

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

// Dashboard - Primary UI with full feature set
class Dashboard<M extends Meta = {}, B extends Body = {}> extends UIPlugin<DashboardOptions<M, B>>;

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

// Progress Display
class ProgressBar<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ProgressBarOptions>;
class StatusBar<M extends Meta = {}, B extends Body = {}> extends UIPlugin<StatusBarOptions<M, B>>;
class Informer<M extends Meta = {}, B extends Body = {}> extends UIPlugin<InformerOptions>;

UI Plugins

File Sources

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

// Media Capture
class Webcam<M extends Meta = {}, B extends Body = {}> extends UIPlugin<WebcamOptions>;
class Audio<M extends Meta = {}, B extends Body = {}> extends UIPlugin<AudioOptions>;
class ScreenCapture<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ScreenCaptureOptions>;

// File Processing
class ImageEditor<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ImageEditorOptions>;
class Compressor<M extends Meta = {}, B extends Body = {}> extends BasePlugin<CompressorOptions>;

File Sources

Cloud Providers

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

// Cloud Storage
class GoogleDrive<M extends Meta = {}, B extends Body = {}> extends BasePlugin<GoogleDriveOptions>;
class GoogleDrivePicker<M extends Meta = {}, B extends Body = {}> extends UIPlugin<GoogleDrivePickerOptions>;
class Dropbox<M extends Meta = {}, B extends Body = {}> extends BasePlugin<DropboxOptions>;
class Box<M extends Meta = {}, B extends Body = {}> extends BasePlugin<BoxOptions>;
class OneDrive<M extends Meta = {}, B extends Body = {}> extends BasePlugin<OneDriveOptions>;

// Social Media
class Instagram<M extends Meta = {}, B extends Body = {}> extends BasePlugin<InstagramOptions>;
class Facebook<M extends Meta = {}, B extends Body = {}> extends BasePlugin<FacebookOptions>;
class Unsplash<M extends Meta = {}, B extends Body = {}> extends BasePlugin<UnsplashOptions>;

Cloud Providers

Upload Handlers

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

// Upload Protocols
class Tus<M extends Meta = {}, B extends Body = {}> extends BasePlugin<TusOptions>;
class XHRUpload<M extends Meta = {}, B extends Body = {}> extends BasePlugin<XHRUploadOptions<M, B>>;
class AwsS3<M extends Meta = {}, B extends Body = {}> extends BasePlugin<AwsS3Options>;

// Processing Services  
class Transloadit<M extends Meta = {}, B extends Body = {}> extends BasePlugin<TransloaditOptions>;

Upload Handlers

Utility Plugins

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

// File Processing
class ThumbnailGenerator<M extends Meta = {}, B extends Body = {}> extends BasePlugin<ThumbnailGeneratorOptions>;

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

// Development Tools
class ReduxDevTools<M extends Meta = {}, B extends Body = {}> extends BasePlugin<any>;

Utility Plugins

Plugin Architecture

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

abstract class BasePlugin<Options, State = {}, Events = {}> {
  constructor(uppy: Uppy<any, any>, options?: Options);
  
  abstract install(): void;
  abstract uninstall(): void;
  
  // Plugin lifecycle
  protected setOptions(newOptions: Partial<Options>): void;
  protected getPluginState(): State;
  protected setPluginState(patch: Partial<State>): void;
}

abstract class UIPlugin<Options, State = {}> extends BasePlugin<Options, State> {
  protected render(): ComponentChild;
  protected mount(target: string | Element, plugin: UIPlugin<any, any>): void;
  protected unmount(): void;
}

Plugin Architecture

TypeScript Support

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

// Core types
interface UppyOptions<M extends Meta = {}, B extends Body = {}> {
  id?: string;
  autoProceed?: boolean;
  allowMultipleUploads?: boolean;
  debug?: boolean;
  restrictions?: Restrictions;
  meta?: M;
  onBeforeFileAdded?: (currentFile: UppyFile<M, B>, files: { [fileId: string]: UppyFile<M, B> }) => UppyFile<M, B> | boolean | undefined;
  onBeforeUpload?: (files: { [fileId: string]: UppyFile<M, B> }) => { [fileId: string]: UppyFile<M, B> } | boolean | undefined;
  locale?: Locale;
  store?: Store;
  logger?: Logger;
  infoTimeout?: number;
}

// File types
interface UppyFile<M extends Meta = {}, B extends Body = {}> {
  id: string;
  name: string;
  extension: string;
  meta: M & UppyFileMeta;
  type?: string;
  data: Blob | File;
  progress?: FileProgress;
  size: number;
  isGhost: boolean;
  source?: string;
  remote?: Remote;
  preview?: string;
}

// Event system
interface UppyEventMap<M extends Meta = {}, B extends Body = {}> {
  'file-added': (file: UppyFile<M, B>) => void;
  'file-removed': (file: UppyFile<M, B>, reason?: string) => void;
  'upload': (data: { id: string; fileIDs: string[] }) => void;
  'upload-progress': (file: UppyFile<M, B>, progress: FileProgress) => void;
  'upload-success': (file: UppyFile<M, B>, response: UploadSuccessResponse<B>) => void;
  'complete': (result: UploadResult<M, B>) => void;
  // ... additional events
}

TypeScript Support

Core Types

interface State<M extends Meta = {}, B extends Body = {}> {
  files: { [fileId: string]: UppyFile<M, B> };
  currentUploads: { [uploadId: string]: CurrentUpload<M, B> };
  allowNewUpload: boolean;
  capabilities: Capabilities;
  totalProgress: number;
  meta: M;
  info: InfoObject | null;
  plugins: { [pluginId: string]: BasePlugin<any, any, any> };
}

interface Meta {
  [key: string]: any;
}

interface Body {
  [key: string]: any;
}

interface Restrictions {
  maxFileSize?: number | null;
  minFileSize?: number | null;
  maxTotalFileSize?: number | null;
  maxNumberOfFiles?: number | null;
  minNumberOfFiles?: number | null;
  allowedFileTypes?: string[] | null;
  requiredMetaFields?: string[];
}

interface FileProgress {
  percentage: number;
  bytesUploaded: number;
  bytesTotal: number;
  uploadComplete: boolean;
  uploadStarted: number | null;
}

interface UploadResult<M extends Meta = {}, B extends Body = {}> {
  successful: UppyFile<M, B>[];
  failed: UppyFile<M, B>[];
  uploadID: string;
}