CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-uppy--core

Core module for the 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

—

Pending
Overview
Eval results
Files

uppy-class.mddocs/

Core Uppy Class

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

Constructor

constructor(opts?: UppyOptions<M, B>)

Constructor Options

interface UppyOptions<M extends Meta = Meta, B extends Body = Body> {
  id?: string;                     // Instance identifier (default: 'uppy')
  autoProceed?: boolean;           // Auto-start uploads (default: false)
  allowMultipleUploadBatches?: boolean; // Allow multiple batches (default: true)
  debug?: boolean;                 // Enable debug logging (default: false)
  restrictions?: Partial<Restrictions>; // File restrictions
  meta?: Partial<M>;              // Default file metadata
  locale?: Locale;                // Localization settings
  store?: Store;                  // Custom state store
  logger?: typeof debugLogger;    // Custom logger
  infoTimeout?: number;           // Info message duration (default: 5000ms)
  onBeforeFileAdded?: (
    currentFile: UppyFile<M, B>,
    files: { [key: string]: UppyFile<M, B> }
  ) => boolean | Promise<boolean>;
  onBeforeUpload?: (
    files: { [key: string]: UppyFile<M, B> }
  ) => boolean | Promise<boolean>;
}

Static Properties

static VERSION: string;  // Package version

State Management

Get and Set State

getState(): State<M, B>;
setState(patch?: Partial<State<M, B>>): void;

File-Specific State Updates

setFileState(fileID: string, state: Partial<UppyFile<M, B>>): void;
patchFilesState(filesWithNewState: {
  [id: string]: Partial<UppyFile<M, B>>
}): void;

Options Updates

setOptions(newOpts: Partial<UppyOptions<M, B>>): void;

File Management

Adding Files

addFile(file: File | MinimalRequiredUppyFile<M, B>): string;
addFiles(fileDescriptors: MinimalRequiredUppyFile<M, B>[]): void;

Parameters:

  • file: Browser File object or minimal file descriptor
  • fileDescriptors: Array of file descriptors

Returns: addFile returns the generated file ID

Removing Files

removeFile(fileID: string): void;
removeFiles(fileIDs: string[]): void;

Retrieving Files

getFile(fileID: string): UppyFile<M, B>;
getFiles(): UppyFile<M, B>[];
getFilesByIds(ids: string[]): UppyFile<M, B>[];
getObjectOfFilesPerState(): {
  newFiles: UppyFile<M, B>[];
  startedFiles: UppyFile<M, B>[];
  uploadStartedFiles: UppyFile<M, B>[];
  pausedFiles: UppyFile<M, B>[];
  completeFiles: UppyFile<M, B>[];
  erroredFiles: UppyFile<M, B>[];
  inProgressFiles: UppyFile<M, B>[];
  inProgressNotPausedFiles: UppyFile<M, B>[];
  processingFiles: UppyFile<M, B>[];
  isUploadStarted: boolean;
  isAllComplete: boolean;
  isAllErrored: boolean;
  isAllPaused: boolean;
  isUploadInProgress: boolean;
  isSomeGhost: boolean;
};

File Existence Check

checkIfFileAlreadyExists(fileID: string): boolean;

Upload Control

Starting Uploads

upload(): Promise<UploadResult<M, B> | undefined>;

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

Pause and Resume

pauseResume(fileID: string): boolean | undefined;
pauseAll(): void;
resumeAll(): void;

Parameters:

  • fileID: Specific file to pause/resume

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

Retry Operations

retryAll(): Promise<UploadResult<M, B> | undefined>;
retryUpload(fileID: string): Promise<UploadResult<M, B> | undefined>;

Cancel Operations

cancelAll(): void;

Event System

Event Subscription

on<K extends keyof UppyEventMap<M, B>>(
  event: K,
  callback: UppyEventMap<M, B>[K]
): this;

once<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;

Event Emission

emit<K extends keyof UppyEventMap<M, B>>(
  event: K,
  ...args: Parameters<UppyEventMap<M, B>[K]>
): void;

Validation

File Validation

validateRestrictions(
  file: ValidateableFile<M, B>,
  files?: ValidateableFile<M, B>[]
): RestrictionError<M, B> | null;

validateSingleFile(file: ValidateableFile<M, B>): string | null;
validateAggregateRestrictions(
  files: ValidateableFile<M, B>[]
): string | null;

Parameters:

  • file: File to validate
  • files: All files for aggregate validation

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

Metadata Management

Global Metadata

setMeta(data: Partial<M>): void;

File-Specific Metadata

setFileMeta(fileID: string, data: Partial<M>): void;

Plugin Management

Plugin Installation

use<T extends typeof BasePlugin<any, M, B>>(
  Plugin: T,
  ...args: OmitFirstArg<ConstructorParameters<T>>
): this;

Plugin Access

getPlugin<T extends UnknownPlugin<M, B> = UnknownPlugin<M, B>>(
  id: string
): T | undefined;
iteratePlugins(method: (plugin: UnknownPlugin<M, B>) => void): void;

Plugin Removal

removePlugin(instance: UnknownPlugin<M, B>): void;

Processing Pipeline

Preprocessors

addPreProcessor(fn: Processor): void;
removePreProcessor(fn: Processor): boolean;

Uploaders

addUploader(fn: Processor): void;
removeUploader(fn: Processor): boolean;

Postprocessors

addPostProcessor(fn: Processor): void;
removePostProcessor(fn: Processor): boolean;

Processor Type:

type Processor = (
  fileIDs: string[],
  uploadID: string
) => Promise<unknown> | void;

Utility Methods

Instance Management

getID(): string;
clear(): void;
resetProgress(): void;
destroy(): void;

Upload State Management

restore(uploadID: string): Promise<UploadResult<M, B> | undefined>;
addResultData(uploadID: string, data: any): void;

Remote File Support

registerRequestClient(id: string, client: unknown): void;
getRequestClientForFile<Client>(file: UppyFile<M, B>): Client;
logout(): void;

User Communication

info(
  message: string | { message: string; details: string },
  type?: 'info' | 'warning' | 'error' | 'success',
  duration?: number
): void;
hideInfo(): void;
log(message: unknown, type?: 'error' | 'warning'): void;

Network Status

updateOnlineStatus(): void;

Public Properties

opts: UppyOptions<M, B>;           // Current options
store: Store;                      // State store instance
locale: Locale;                    // Current locale
i18n: I18n;                       // Translation function
i18nArray: Translator['translateArray']; // Array translation

Usage Examples

Basic File Upload

import Uppy from '@uppy/core';

const uppy = new Uppy({
  restrictions: {
    maxFileSize: 5 * 1024 * 1024, // 5MB
    allowedFileTypes: ['image/*']
  }
});

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

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

// Add files and upload
const fileInput = document.querySelector('#file-input');
fileInput.addEventListener('change', (event) => {
  const files = Array.from(event.target.files);
  files.forEach(file => uppy.addFile(file));
  uppy.upload();
});

Custom Validation

const uppy = new Uppy({
  onBeforeFileAdded: (currentFile, files) => {
    // Custom validation logic
    if (currentFile.name.includes('temp')) {
      uppy.info('Temporary files are not allowed', 'error');
      return false;
    }
    return true;
  },
  onBeforeUpload: (files) => {
    // Pre-upload validation
    const fileCount = Object.keys(files).length;
    if (fileCount === 0) {
      uppy.info('Please select at least one file', 'error');
      return false;
    }
    return true;
  }
});

Plugin Integration

import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import XHRUpload from '@uppy/xhr-upload';

const uppy = new Uppy()
  .use(Dashboard, {
    target: '#uppy-dashboard',
    inline: true
  })
  .use(XHRUpload, {
    endpoint: '/upload',
    headers: {
      'Authorization': 'Bearer token'
    }
  });

Install with Tessl CLI

npx tessl i tessl/npm-uppy--core

docs

event-management.md

file-validation.md

index.md

plugin-development.md

type-system.md

uppy-class.md

tile.json