Configuration Options

Every Resumable.js instance starts with a configuration object passed to the constructor. These options control where chunks go, how large they are, how many fly in parallel, what happens on failure, and how files get validated before they ever touch the network. This reference covers every available option with types, defaults, and practical notes on when to change them. For the full API surface, see the API hub.

Constructor Usage

var r = new Resumable({
  target: '/api/upload',
  chunkSize: 1 * 1024 * 1024,
  simultaneousUploads: 3,
  // ...additional options
});

Upload Target Options

Option	Type	Default	Description
target	string	'/'	The endpoint that receives POST requests for each chunk. Can also be a function returning a string, evaluated per chunk — useful for signed URLs or rotating endpoints.
testTarget	string | null	null	The endpoint for GET requests when testChunks is enabled. Defaults to the value of target if not set.
method	string	'multipart'	Upload method. 'multipart' sends the chunk as a multipart form field. 'octet' sends raw binary in the request body.
uploadMethod	string	'POST'	HTTP method for chunk uploads. Override to 'PUT' for endpoints that expect it.
testMethod	string	'GET'	HTTP method for chunk existence checks when testChunks is true.

Chunk Behavior

Option	Type	Default	Description
chunkSize	number	1048576 (1 MB)	Size of each chunk in bytes. Smaller chunks mean more HTTP requests but finer resume granularity. Larger chunks reduce overhead but increase the cost of a single retry. Finding the sweet spot depends on your users' typical connection speeds.
forceChunkSize	boolean	false	When true, forces every chunk (including the last one) to be exactly chunkSize bytes by padding. Rarely needed — most servers handle a smaller final chunk just fine.
simultaneousUploads	number	3	Number of chunks uploaded in parallel. Increasing this saturates bandwidth faster but may overwhelm servers or trigger rate limits. Three is a sensible default for most environments.
testChunks	boolean	true	When true, sends a GET request for each chunk before uploading to check if it already exists on the server. This is the mechanism that enables resuming after interruption. Set to false if your server doesn't support chunk checks.
prioritizeFirstAndLastChunk	boolean	false	When true, the first and last chunks upload before the middle ones. Useful for media files where the server needs header and trailer data early for metadata extraction or validation.
preprocess	function | null	null	A function called before each chunk upload. Receives the ResumableChunk object. Call chunk.preprocessFinished() when done. Use this for client-side encryption, compression, or custom headers per chunk.

Parameter Names

These control the form field names sent with each chunk request. Only change them if your server expects non-default parameter names.

Option	Type	Default	Description
fileParameterName	string	'file'	The multipart form field name for the chunk data.
chunkNumberParameterName	string	'resumableChunkNumber'	Parameter name for the current chunk index (1-based).
chunkSizeParameterName	string	'resumableChunkSize'	Parameter name for the configured chunk size.
currentChunkSizeParameterName	string	'resumableCurrentChunkSize'	Parameter name for the actual byte size of this specific chunk.
totalSizeParameterName	string	'resumableTotalSize'	Parameter name for the total file size.
identifierParameterName	string	'resumableIdentifier'	Parameter name for the unique file identifier.
fileNameParameterName	string	'resumableFilename'	Parameter name for the original file name.
relativePathParameterName	string	'resumableRelativePath'	Parameter name for the relative path (when uploading folder structures).
totalChunksParameterName	string	'resumableTotalChunks'	Parameter name for the total number of chunks in the file.

Request Options

Option	Type	Default	Description
query	object or function	empty object	Additional query parameters or POST data sent with every chunk request. If a function, receives the file, chunk, and a boolean indicating whether it's a test request.
headers	object or function	empty object	Additional HTTP headers sent with every chunk request. If a function, receives the file and chunk. Commonly used for authorization tokens.
withCredentials	boolean	false	Sets XMLHttpRequest.withCredentials to send cookies and auth headers in cross-origin requests. Required when your upload endpoint is on a different subdomain and uses cookie-based authentication.

Retry Configuration

Option	Type	Default	Description
maxChunkRetries	number	0	Number of times to retry a failed chunk before triggering the error event. Set to 2 or 3 for unstable networks. Zero means no retries.
chunkRetryInterval	number | null	null	Milliseconds to wait between retries. null retries immediately. A value like 5000 gives transient server errors time to resolve.
permanentErrors	array	[404, 415, 500, 501]	HTTP status codes that should not be retried. If the server returns one of these, the chunk fails immediately regardless of maxChunkRetries. Remove 500 from this list if your server sometimes returns recoverable 500s.

File Validation

Option	Type	Default	Description
maxFiles	number | undefined	undefined	Maximum number of files allowed in the queue. undefined means no limit.
maxFileSize	number | undefined	undefined	Maximum file size in bytes. Files exceeding this are rejected via maxFileSizeErrorCallback.
minFileSize	number | undefined	undefined	Minimum file size in bytes. Useful for rejecting empty or trivially small files.
fileType	array	[]	Allowed file extensions (without dots), e.g. ['png', 'jpg', 'pdf']. An empty array allows all types. Checked against the file name extension, not the MIME type.
fileTypeErrorCallback	function	default handler	Called when a file is rejected due to type mismatch. Receives file and errorCount.
maxFileSizeErrorCallback	function	default handler	Called when a file exceeds maxFileSize. Receives file and errorCount.
minFileSizeErrorCallback	function	default handler	Called when a file is smaller than minFileSize. Receives file and errorCount.

Advanced Options

Option	Type	Default	Description
throttleProgressCallbacks	number	0.5	Minimum interval in seconds between fileProgress / progress event calls. Prevents excessive DOM updates during fast uploads. Set to 0 for real-time updates at the cost of more frequent repaints.
generateUniqueIdentifier	function | null	null	Custom function to generate the unique identifier for each file. Receives the file object. The default identifier is size-filename. Override this when you need deterministic IDs for resume-after-refresh workflows or to avoid collisions.
maxFiles	number | undefined	undefined	Maximum number of files that can be added to the queue.

Practical Defaults

For most applications uploading files under 100 MB on typical broadband connections, these defaults work well:

var r = new Resumable({
  target: '/api/upload',
  chunkSize: 2 * 1024 * 1024,   // 2 MB — good balance
  simultaneousUploads: 3,
  testChunks: true,
  maxChunkRetries: 2,
  chunkRetryInterval: 3000,
  permanentErrors: [400, 404, 415, 500, 501],
  withCredentials: false
});

For large file uploads (1 GB+), increase chunkSize to 5–10 MB and consider lowering simultaneousUploads to 2 to avoid saturating the connection. For mobile users on cellular networks, smaller chunks (512 KB) with higher maxChunkRetries gives a more resilient experience.

Configuration isn't set-and-forget — profile your real-world usage, then adjust.