API Reference

This reference matches the bundled runtime and TypeScript declarations in this package.

new MultipleUpload(container, options)

Upload Options

Option	Type	Default	Description
uploadUrl	string	'/api/upload'	Single-request upload endpoint.
chunked	boolean	false	Enables chunked upload flow.
chunkSize	number	5 * 1024 * 1024	Chunk size in bytes.
autoUpload	boolean	true	Starts uploads as soon as files enter the queue.
multiple	boolean	false	Allows multi-file selection in the file input.
accept	string	''	Native file input accept attribute override.
allowedExtensions	string	''	Comma-separated extension list such as '.jpg,.png,.pdf'.
allowedMimeTypes	string	''	Comma-separated MIME patterns such as 'image/*,application/pdf'.
maxFileSize	number	-1	Maximum file size in bytes. -1 disables the limit.
minFileSize	number	0	Minimum file size in bytes.
maxFiles	number	0	Maximum queued files. 0 means unlimited.
concurrency	number	1	Number of active uploads allowed at once.
retries	number	2	Retry attempts for failed uploads or chunks.
retryDelay	number	1000	Base retry delay in milliseconds.
retryBackoff	'linear' \| 'exponential'	'exponential'	Retry delay strategy.
timeout	number	0	XHR timeout in milliseconds. 0 disables timeouts.

Display and UI Options

Option	Type	Default	Description
dropZoneMode	boolean	false	Optimizes the layout for a drop-zone-first UI.
attachmentMode	boolean	false	Uses a compact attachment list layout.
showFileSize	boolean	true	Shows file sizes in the queue.
removable	boolean	true	Shows remove controls for completed items.
showThumbnails	boolean	true	Generates image and video thumbnails when possible.
thumbnailSize	number	64	Preview thumbnail size in pixels.
showToasts	boolean	true	Enables built-in toast notifications.
confirmRemove	boolean	false	Prompts before removing queue items.
sortable	boolean	false	Flags the queue as sortable when your UI supports it.
sortBy	'priority' \| function \| null	null	Sort strategy for pending tasks.
filterStatus	string \| null	null	Only shows tasks matching a specific status.

Backend, paste, and image pipeline options

Option	Type	Default	Description
headers	object \| function(task)	{}	Static or per-task request headers.
withCredentials	boolean	false	Sends credentials on cross-origin requests.
fieldName	string	'file'	Multipart field name for the upload.
chunkUrl	string \| null	null	Explicit chunk upload endpoint.
chunkCompleteUrl	string \| null	null	Explicit chunk assembly endpoint.
deleteUrl	string \| null	null	Optional endpoint for deleting uploaded files.
responseParser	function(responseText, task)	null	Maps server responses into the expected result object.
method	string	'POST'	HTTP method for single-request uploads.
licenseUrl	string \| false \| null	auto	Explicit path to multipleupload.lic. Defaults to a sibling file next to multipleupload.js.
autoLoadLicense	boolean	true	Automatically fetches the license file during startup.
licenseFetchOptions	RequestInit \| null	null	Optional fetch settings used when loading multipleupload.lic.
paste	boolean	true	Enables clipboard paste support.
pasteTarget	string \| HTMLElement \| null	null	Paste focus target. Falls back to the uploader container.
fullPageDrop	boolean	false	Shows a full-page drop overlay when dragging files over the page.
fullPageDropText	string \| null	null	Custom full-page drop overlay text.
imageResize	object \| null	null	Resize images before upload.
imageCompress	object \| null	null	Compress images to a lower quality level.
imageCrop	object \| null	null	Crop images before upload.
imageRotate	number	0	Rotate images by degrees before upload.
autoOrient	boolean	false	Fixes image orientation using EXIF metadata.
watermark	object \| null	null	Adds a text watermark to images.
generateVideoThumbs	boolean	true	Generates thumbnails for supported video files.

Validation, hashing, state, and accessibility

Option	Type	Default	Description
preventDuplicates	boolean	false	Blocks repeated files based on name and size.
validateMimeByMagic	boolean	false	Validates file content via magic bytes instead of only using file.type.
maxImageWidth	number	0	Maximum allowed image width. 0 disables the limit.
maxImageHeight	number	0	Maximum allowed image height.
minImageWidth	number	0	Minimum allowed image width.
minImageHeight	number	0	Minimum allowed image height.
customValidation	function(file, uploader)	null	Returns a validation error string or a promise resolving to one.
computeHash	boolean	false	Computes a file checksum before uploading.
hashAlgorithm	'crc32' \| 'sha256'	'crc32'	Selects the checksum algorithm.
persistState	boolean	false	Saves completed file metadata in localStorage.
persistKey	string	'mu-state'	localStorage key for persisted completed file data.
transformPipeline	function \| function[] \| null	null	Custom synchronous or asynchronous file transforms.
ariaLabel	string	'File uploader'	ARIA label applied to the uploader container.
ariaDescribedBy	string \| null	null	Optional element id for screen-reader descriptions.
locale	string	'en'	Active locale key used by the built-in text labels.

Common Callbacks

Callback	Signature	Description
onSelect	(files, uploader)	Return false to cancel selection or a filtered file array to replace the selection.
onProgress	(overallProgress, uploader)	Overall queue progress updates.
onComplete	(completedFiles, uploader)	Fires once all active uploads finish.
onError	(message, fileName, uploader)	General upload or validation errors.
onTaskStart	(task, uploader)	Individual task started uploading.
onTaskComplete	(task, result, uploader)	Individual task completed successfully.
onTaskError	(task, error, uploader)	Individual task failed.
onTaskProgress	(task, uploader)	Per-file upload progress updates.
onTaskPause / onTaskResume	(task, uploader)	Pause and resume lifecycle hooks.
onChange	(completedFiles, uploader)	Completed files list changed.
onQueueRender	(tasks, queueEl, uploader)	Override or enhance queue rendering.
onPaste	(files, uploader)	Return false to block pasted files.
onDrop	(event, uploader)	Receives the original drop event.
onBeforeUpload	(task, uploader)	Return false to block upload for a task.
onAfterUpload	(task, result, uploader)	Runs after a task finishes and the result is stored.
onValidationError	(message, fileName, uploader)	Validation-specific error hook.
onImageProcessed	(processedFile, originalFile, uploader)	Fires after image transforms run.
onHashComputed	(task, hash, uploader)	Receives the generated checksum.

Instance Methods and Static Helpers

Chainable instance methods

uploader.upload()
    .pauseAll()
    .resumeAll()
    .clearCompleted();

uploader.getCompletedFiles();
uploader.getStats();
uploader.setOptions({ locale: 'en' });

Static helpers

MultipleUpload.formatSize(bytes);
MultipleUpload.computeSHA256(file);
MultipleUpload.resizeImage(file, 1200, 1200, 0.82);
MultipleUpload.showToast('Saved', 'success');
MultipleUpload.waitForLicense().then(function(info) { console.log(info); });
MultipleUpload.loadLicense('/licenses/multipleupload.lic');
MultipleUpload.getLicenseInfo();
MultipleUpload.registerLocale('fr', strings);