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.
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);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);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;
}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;
}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;
}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;
}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;
}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;
}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;
}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');
});