tessl/npm-blueimp-file-upload

jQuery File Upload widget with multiple file selection, drag-and-drop support, progress bars, validation and preview images, audio and video

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Widget

Name: tessl/npm-blueimp-file-upload
Author: tessl

The core jQuery File Upload widget provides essential file upload functionality including drag-and-drop support, multiple file selection, progress tracking, chunked uploads, and a comprehensive event system.

Capabilities

Widget Initialization

Initialize the file upload widget on any file input element or container.

/**
 * Initialize jQuery File Upload widget
 * @param options - Configuration options object
 * @returns jQuery object for chaining
 */
$('#fileupload').fileupload(options);

Widget Methods

Methods available on the widget instance for controlling uploads and retrieving status.

/**
 * Get number of active uploads
 * @returns number - Count of currently active uploads
 */
.fileupload('active');

/**
 * Get upload progress information
 * @returns object - Progress object with loaded, total, and bitrate properties
 */
.fileupload('progress');

/**
 * Add files programmatically to upload queue
 * @param data - Data object containing files array or fileInput element
 * @returns Promise-like object with abort() method
 */
.fileupload('add', data);

/**
 * Send files immediately without queuing
 * @param data - Data object containing files to send
 * @returns Promise-like object with abort() method  
 */
.fileupload('send', data);

/**
 * Get or set widget options
 * @param key - Option name or options object
 * @param value - Option value (when setting single option)
 * @returns Mixed - Option value when getting, jQuery object when setting
 */
.fileupload('option', key, value);

/**
 * Destroy widget instance and clean up event handlers
 * @returns jQuery object for chaining
 */
.fileupload('destroy');

/**
 * Get number of files currently being processed
 * @returns number - Count of files in processing queue
 */
.fileupload('processing');

/**
 * Process files through the processing queue
 * @param data - Data object containing files to process
 * @returns Promise - Resolves when processing completes
 */
.fileupload('process', data);

Core Configuration Options

Essential configuration options for controlling upload behavior.

interface FileUploadOptions {
    /** Drop target element(s), default: $(document) */
    dropZone?: JQuery;
    
    /** Paste target element(s), default: undefined */
    pasteZone?: JQuery;
    
    /** File input field(s), auto-detected if undefined */
    fileInput?: JQuery;
    
    /** Replace file input after each change, default: true */
    replaceFileInput?: boolean;
    
    /** Parameter name for file form data, default: input name or "files[]" */
    paramName?: string | string[];
    
    /** Upload each file individually, default: true */
    singleFileUploads?: boolean;
    
    /** Max files per XHR request, default: undefined */
    limitMultiFileUploads?: number;
    
    /** Max total size per XHR request, default: undefined */
    limitMultiFileUploadSize?: number;
    
    /** Overhead per file in size calculation, default: 512 */
    limitMultiFileUploadSizeOverhead?: number;
    
    /** Upload files sequentially, default: false */
    sequentialUploads?: boolean;
    
    /** Max concurrent uploads, default: undefined */
    limitConcurrentUploads?: number;
    
    /** Start uploads automatically, default: true */
    autoUpload?: boolean;
}

Upload Configuration Options

Options for controlling the upload request and transport behavior.

interface UploadOptions {
    /** Force iframe transport, default: false */
    forceIframeTransport?: boolean;
    
    /** Cross-domain iframe redirect URL, default: undefined */
    redirect?: string;
    
    /** Redirect parameter name, default: undefined */
    redirectParamName?: string;
    
    /** PostMessage transport window location, default: undefined */
    postMessage?: string;
    
    /** Use multipart/form-data, default: true */
    multipart?: boolean;
    
    /** Chunk size for chunked uploads, default: undefined */
    maxChunkSize?: number;
    
    /** Already uploaded bytes for resume, default: undefined */
    uploadedBytes?: number;
    
    /** Recalculate progress on failures, default: true */
    recalculateProgress?: boolean;
    
    /** Progress event interval (ms), default: 100 */
    progressInterval?: number;
    
    /** Bitrate calculation interval (ms), default: 500 */
    bitrateInterval?: number;
    
    /** Map for unique filename generation, default: undefined */
    uniqueFilenames?: object;
}

Form Data Options

Options for including additional data with uploads.

interface FormDataOptions {
    /** Additional form data to send */
    formData?: Function | FormData | Array | object;
    
    /** jQuery AJAX setting, default: false */
    processData?: boolean;
    
    /** jQuery AJAX setting, default: false */  
    contentType?: boolean;
    
    /** jQuery AJAX setting, default: false */
    cache?: boolean;
    
    /** jQuery AJAX setting (ms), default: 0 */
    timeout?: number;
}

Core Events

Event callbacks fired during the upload lifecycle.

interface CoreEvents {
    /** Files added to upload queue */
    add?: (e: Event, data: FileUploadData) => void;
    
    /** Before file upload submission */
    submit?: (e: Event, data: FileUploadData) => void;
    
    /** Upload request started */
    send?: (e: Event, data: FileUploadData) => void;
    
    /** Upload completed successfully */
    done?: (e: Event, data: FileUploadData) => void;
    
    /** Upload failed or was aborted */
    fail?: (e: Event, data: FileUploadData) => void;
    
    /** Upload completed (success, fail, or abort) */
    always?: (e: Event, data: FileUploadData) => void;
    
    /** Individual file upload progress */
    progress?: (e: Event, data: FileUploadData) => void;
    
    /** Global upload progress for all files */
    progressall?: (e: Event, data: FileUploadData) => void;
    
    /** First upload started (equivalent to ajaxStart) */
    start?: (e: Event) => void;
    
    /** All uploads completed (equivalent to ajaxStop) */
    stop?: (e: Event) => void;
}

interface ProcessingEvents {
    /** File processing started */
    process?: (e: Event, data: FileUploadData) => void;
    
    /** File processing completed successfully */
    processdone?: (e: Event, data: FileUploadData) => void;
    
    /** File processing failed */
    processfail?: (e: Event, data: FileUploadData) => void;
    
    /** File processing finished (success or fail) */
    processalways?: (e: Event, data: FileUploadData) => void;
    
    /** Processing queue started */
    processstart?: (e: Event) => void;
    
    /** Processing queue stopped */
    processstop?: (e: Event) => void;
}

File Input Events

Events related to file selection and drag-and-drop operations.

interface FileInputEvents {
    /** File input selection changed */
    change?: (e: Event, data: FileUploadData) => void;
    
    /** Files pasted into paste zone */
    paste?: (e: Event, data: FileUploadData) => void;
    
    /** Files dropped into drop zone */
    drop?: (e: Event, data: FileUploadData) => void;
    
    /** Drag over drop zone */
    dragover?: (e: Event) => void;
}

Chunked Upload Events

Events specific to chunked file uploads for large files.

interface ChunkedUploadEvents {
    /** Before chunk upload (before form data init) */
    chunkbeforesend?: (e: Event, data: FileUploadData) => void;
    
    /** Chunk upload started */
    chunksend?: (e: Event, data: FileUploadData) => void;
    
    /** Chunk upload completed successfully */
    chunkdone?: (e: Event, data: FileUploadData) => void;
    
    /** Chunk upload failed */
    chunkfail?: (e: Event, data: FileUploadData) => void;
    
    /** Chunk upload completed (success or fail) */
    chunkalways?: (e: Event, data: FileUploadData) => void;
}

Data Object Structure

The data object passed to event callbacks containing upload information and control methods.

interface FileUploadData {
    /** Array of File objects */
    files: File[];
    
    /** Original file selection before processing */
    originalFiles: File[];
    
    /** Current file index in processing */
    index: number;
    
    /** Associated file input element */
    fileInput: JQuery;
    
    /** Associated form element */
    form: JQuery;
    
    /** UI context element for the upload */
    context: JQuery;
    
    /** jQuery XHR object for the request */
    jqXHR: JQueryXHR;
    
    /** Server response data */
    result: any;
    
    /** HTTP status text */
    textStatus: string;
    
    /** Error message if failed */
    errorThrown: string;
    
    /** Submit the upload, returns Promise */
    submit(): JQueryPromise<any>;
    
    /** Abort the upload */
    abort(): void;
    
    /** Get current state ('pending', 'resolved', 'rejected') */
    state(): string;
    
    /** Get progress object */
    progress(): object;
    
    /** Get response object */
    response(): object;
}

Browser Support Detection

Properties indicating browser capabilities for file upload features.

/** File input support detection */
$.support.fileInput: boolean;

/** XHR file upload support */
$.support.xhrFileUpload: boolean;

/** XHR FormData upload support */
$.support.xhrFormDataFileUpload: boolean;

/** Blob slicing support (for chunked uploads) */
$.support.blobSlice: boolean;

Usage Examples:

// Basic initialization
$('#fileupload').fileupload({
    url: '/upload',
    dataType: 'json',
    autoUpload: true,
    singleFileUploads: true
});

// Advanced configuration with chunked uploads
$('#fileupload').fileupload({
    url: '/upload',
    maxChunkSize: 1000000, // 1MB chunks
    limitConcurrentUploads: 3,
    sequentialUploads: false,
    add: function (e, data) {
        console.log('Added', data.files.length, 'files');
        data.submit();
    },
    progress: function (e, data) {
        var progress = parseInt(data.loaded / data.total * 100, 10);
        console.log('Progress:', progress + '%');
    }
});

// Programmatic file addition
var files = [new File(['content'], 'test.txt', {type: 'text/plain'})];
$('#fileupload').fileupload('add', {files: files});

// Check upload status
var activeUploads = $('#fileupload').fileupload('active');
var progress = $('#fileupload').fileupload('progress');

// Check processing status
var processingCount = $('#fileupload').fileupload('processing');

// Manual processing
$('#fileupload').fileupload('process', {
    files: [file1, file2],
    processQueue: [
        { action: 'validate' },
        { action: 'loadImage' }
    ]
}).done(function (data) {
    console.log('Processing completed');
});