5.16.2

Options Core

Fine Uploader has a plethora of options. Many of these options change meaning depending on what sort of uploader you are using. Pay close attention to the mode you are in and keep that in mind when determining the meaning of a particular option.

Core

autoUpload

Set to false if you want to be able to upload queued items later by calling the uploadStoredFiles() method.

Type:
Boolean
Default Value:
true

button

Specify an element to use as the 'select files' button. Cannot be a <button>.

Type:
HTMLElement
Default Value:
null

debug

This will result in log messages being written to the window.console object

Type:
Boolean
Default Value:
false

disableCancelForFormUploads

When true the cancel link does not appear next to files when the form uploader is used.

Type:
Boolean
Default Value:
false

formatFileName

Provide a function to control the display of file names. The raw file name is passed into the function when it is invoked. Your function may return a modified file name. Note that this does not affect the actual file name, only the displayed file name.

Type:
Function
Default Value:

maxConnections

Maximum allowable concurrent requests

Type:
Integer
Default Value:
3

multiple

When false this will prevent the user from simultaneously selecting or dropping more than one item.

Type:
Boolean
Default Value:
true

warnBeforeUnload

When true Fine Uploader will ensure a modal confirmation dialog appears whenever a user tries to navigate away from the page with uploads in progress.

Type:
Boolean
Default Value:
true

blobs

defaultName

The default name to be used for nameless Blobs.

Type:
String
Default Value:
Misc data

callbacks

Provide event handlers for almost any point in the upload process in order to unlock the full potential of Fine Uploader. See the Events page for more details.

camera

button

null allows camera access on the default button in iOS. Otherwise provide an extra button container element to target.

Type:
HTMLElement
Default Value:
null

ios

Enable or disable camera access on iOS (iPod, iPhone, and iPad) devices. Note: Enabling this will disable multiple file selection.

Type:
Boolean
Default Value:
false

Note

The chunking.success.endpoint option only applies to traditional upload endpoints (not S3, Azure, etc).

chunking

concurrent.enabled

Allow multiple chunks to be uploaded simultaneously per file

Type:
Boolean
Default Value:
false

enabled

Enable or disable splitting the file separate chunks. Each chunks is sent in a separate request.

Type:
Boolean
Default Value:
false

mandatory

Ensure every file is uploaded in chunks, even if the file can only be split up into 1 chunk. Does not apply if chunking is not possible in the current browser.

Type:
Boolean
Default Value:
false

partSize

The maximum size of each chunk, in bytes. If a function value is provided, the file's ID will be passed when invoking the function (which should only be called once per file).

Type:
Integer or Function
Default Value:
2000000

paramNames.chunkSize

Name of the parameter passed with a chunked request that specifies the size in bytes of the associated chunk.

Type:
String
Default Value:
qqchunksize

paramNames.partByteOffset

Name of the parameter passed with a chunked request that specifies the starting byte of the associated chunk.

Type:
String
Default Value:
qqpartbyteoffset

paramNames.partIndex

Name of the parameter passed with a chunked request that specifies the index of the associated partition.

Type:
String
Default Value:
qqpartindex

paramNames.totalParts

Name of the parameter passed with a chunked request that specifies the total number of chunks associated with the File or Blob.

Type:
String
Default Value:
qqtotalparts

success.endpoint

Endpoint to send a POST after all chunks have been successfully uploaded for each file. Required if the concurrent.enabled option is set. If a function value is provided, the file's ID will be passed when invoking the function.

Type:
String or Function
Default Value:
null

success.headers

Headers to send to with chunking success request. The file's ID will be passed to your provided function.

Type:
Function
Default Value:
function(fileId) { return null }

success.jsonPayload

Send all parameters in the request body JSON-encoded. Otherwise params will be sent application/x-www-form-urlencoded.

Type:
Boolean
Default Value:
false

success.method

HTTP method used when sending the success request.

Type:
String
Default Value:
POST

success.params

Parameters to send in the message body of the success request. The file's ID will be passed to your provided function.

Type:
Function
Default Value:
function(fileId) { return null }

success.resetOnStatus

Fine Uploader will reset the file such that a retry will start at chunk 0 if the success response status matches any of the provided status codes.

Type:
Array
Default Value:
[]

cors

allowXdr

Enable or disable cross-origin requests from IE9 and older where XDomainRequest must be used.

Type:
Boolean
Default Value:
false

expected

Enable or disable cross-domain requests.

Type:
Boolean
Default Value:
false

sendCredentials

Enable or disable sending credentials along with each cross-domain request. Ignored if allowXdr is true and IE9 is being used.

Type:
Boolean
Default Value:
false

deleteFile

customHeaders

Any additional headers to attach to all delete file requests.

Type:
Object
Default Value:
{}

enabled

Enable or disable deletion of uploaded files.

Type:
Boolean
Default Value:
false

endpoint

The endpoint to which delete file requests are sent.

Type:
String
Default Value:
/server/upload

method

Set the method to use for delete requests. Accepts 'POST' or 'DELETE'

Type:
String
Default Value:
DELETE

params

Any additional parameters to attach to delete file requests.

Type:
Object
Default Value:
{}

extraButtons

This must contain an array of objects. Each object will describe an “extra” button that Fine Uploader will track along with the default upload button. Each button object can contain the following properties:

element

REQUIRED: The container element for the upload button.

Type:
HTMLElement
Default Value:
undefined

fileInputTitle

This value will be used when creating the title attribute for the underlying <input type="file">. If not provided, the text.fileInputTitle option will be used instead.

Type:
String
Default Value:
file input

folders

true to allow folders to be selected, false to allow files to be selected. See the browser support page for details regarding the limited user agent support for this feature.

Type:
Boolean
Default Value:
false

multiple

Specify to override the default multiple value.

Type:
Boolean
Default Value:
true

validation

Specify to override the default validation option specified. Any validation properties not specified will be inherited from the default validation option.

Type:
Object
Default Value:
`validation`

form

Override default values for form support. See the form support feature page for more details.

element

This can be the ID of the <form> or a reference to the <form> element.

Type:
String or HTMLElement
Default Value:
qq-form

autoUpload

If Fine Uploader is able to attach to a form, this value takes the place of the base autoUpload option.

Type:
Boolean
Default Value:
false

interceptSubmit

Set this to false if you do not want Fine Uploader to intercept attempts to submit your form. By default, Fine Uploader will intercept submit attempts and instead upload all submitted files, including data from your form in each upload request.

Type:
Boolean
Default Value:
true

messages

emptyError

Text passed to the error event handler if a submitted item is zero bits.

Type:
String
Default Value:
{file} is empty, please select files again without it.

maxHeightImageError

Text passed to the error event handler if an image is too tall.

Type:
String
Default Value:
Image is too tall.

maxWidthImageError

Text passed to the error event handler if an image is too wide.

Type:
String
Default Value:
Image is too wide.

minHeightImageError

Text passed to the error event handler if an image is not tall enough.

Type:
String
Default Value:
Image is not tall enough.

minWidthImageError

Text passed to the error event handler if an image is not wide enough.

Type:
String
Default Value:
Image is not wide enough.

minSizeError

Text passed to the error event handler if the item is too small.

Type:
String
Default Value:
{file} is too small, minimum file size is {minSizeLimit}.

noFilesError

Text passed to the error event handler if any empty array of items is submitted.

Type:
String
Default Value:
No files to upload.

onLeave

Text displayed to the user when they attempt to leave the page while uploads are still in progress.

Type:
String
Default Value:
The files are being uploaded, if you leave now the upload will be canceled.

retryFailTooManyItemsError

Text passed to the error event handler if a retry attempt is declared a failed due to a violation of the validation.itemLimit rule.

Type:
String
Default Value:
Retry failed - you have reached your file limit.

sizeError

Text passed to the error event handler if a submitted item is too large.

Type:
String
Default Value:
{file} is too large, maximum file size is {sizeLimit}.

tooManyItemsError

Text passed to the error event handler if a submit is ignored due to a violation of the validation.itemLimit rules.

Type:
String
Default Value:
Too many items ({netItems}) would be uploaded. Item limit is {itemLimit}.

typeError

Text passed to the error event handler if an invalid file type is detected.

Type:
String
Default Value:
{file} has an invalid extension. Valid extension(s): {extensions}.

unsupportedBrowserIos8Safari

Message displayed if the browser is iOS8 Safari and the corresponding workarounds option is not disabled.

Type:
String
Default Value:
Unrecoverable error - this browser does not permit file uploading of any kind due to serious bugs in iOS8 Safari. Please use iOS8 Chrome until Apple fixes these issues.

paste

defaultName

The default name given to pasted images.

Type:
String
Default Value:
pasted_image

targetElement

Enable this feature by providing any HTMLElement here.

Type:
HTMLElement
Default Value:
null

resume

customKeys

Define custom keys used to identify this file among other resume records. The file's ID will be passed to your provided function.

Type:
Function
Default Value:
function(fileId) { return [] }

enabled

Enable or disable the ability to resume failed or stopped chunked uploads.

Type:
Boolean
Default Value:
false

paramNames.resuming

Sent with the first request of the resume with a value of true.

Type:
String
Default Value:
qqresume

recordsExpireIn

The number of days before a persistent resume record will expire.

Type:
Integer
Default Value:
7

retry

autoAttemptDelay

The number of seconds to wait between auto retry attempts.

Type:
Integer
Default Value:
5

enableAuto

Enable or disable retrying uploads that receive any error response.

Type:
Boolean
Default Value:
false

maxAutoAttempts

The maximum number of times to attempt to retry a failed upload.

Type:
Integer
Default Value:
3

preventRetryResponseProperty

This property will be looked for in the server response and, if found and true, will indicate that no more retries should be attempted for this item.

Type:
String
Default Value:
preventRetry

request

customHeaders

Additional headers sent along with each upload request.

Type:
Object
Default Value:
{}

endpoint

The endpoint to send upload requests to.

Type:
String
Default Value:
/server/upload

filenameParam

The name of the parameter passed if the original filename has been edited or a Blob is being sent.

Type:
String
Default Value:
qqfilename

forceMultipart

Force all uploads to use multipart encoding

Type:
Boolean
Default Value:
true

inputName

The attribute of the input element which will contain the file name. For non-multipart-encoded upload requests, this will be included as a parameter in the query string of the URI with a value equal to the file name.

Type:
String
Default Value:
qqfile

method

Specify a method to use when sending files to a traditional endpoint. This option is ignored in older browsers (such as IE 9 and older).

Type:
String
Default Value:
POST

omitDefaultParams

If set to true, any Fine Uploader created parameters (qq*) will not be sent with the upload request.

Type:
Boolean
Default Value:
false

params

The parameters that shall be sent with each upload request.

Type:
Object
Default Value:
{}

paramsInBody

Enable or disable sending parameters in the request body. If false, parameters are sent in the URL. Otherwise, parameters are sent in the request body.

Type:
Boolean
Default Value:
true

requireSuccessJson

If set to true, each upload response MUST contain a JSON message-body with {success: true} in order to be considered a success. If set to false, the success of the request is determined by examining the response status code.

Type:
Boolean
Default Value:
true

uuidName

The name of the parameter the uniquely identifies each associated item. The value is a Level 4 UUID.

Type:
String
Default Value:
qquuid

totalFileSizeName

The name of the parameter passed that specifies the total file size in bytes.

Type:
String
Default Value:
qqtotalfilesize

scaling

See the Upload Scaled Images feature page for more details.

customResizer

Ignored if the current browser does not support image previews. If you want to use an alternate scaling library, you must contribute a function for this option that returns a Promise. Once the resize is complete, your promise must be fulfilled. You may, of course, reject your returned Promise is the resize fails in some way.

A `resizeInfo` object, which will be passed to the supplied function, contains the following properties:
  • blob - The original File or Blob object, if available.
  • height - Desired height of the image after the resize operation.
  • image - The original HTMLImageElement object, if available.
  • sourceCanvas - HTMLCanvasElement element containing the original image data (not resized).
  • targetCanvas - HTMLCanvasElement element containing the HTMLCanvasElement that should contain the resized image.
  • width - Desired width of the image after the resize operation.
Type:
Function
Default Value:
undefined

defaultQuality

A value between 1 and 100 that describes the requested quality of scaled images. Ignored unless the scaled image type target is image/jpeg.

Type:
Integer
Default Value:
80

defaultType

Scaled images will assume this image type if you don't specify a specific type in your size object, or if the type specified in the size object is not valid. You generally should not use any value other than image/jpeg or image/png here. The default value of null will ensure the scaled image type is PNG, unless the original file is a JPEG, in which case the scaled file will also be a JPEG. The default is probably the safest option.

Type:
String
Default Value:
null

failureText

Text sent to your complete event handler as an error property of the response param if a scaled image could not be generated.

Type:
String
Default Value:
Failed to scale

includeExif

Ensure the EXIF data from the reference image is inserted into the scaled image. Only applicable when both the reference and the target are type image/jpeg.

Type:
Boolean
Default Value:
false

orient

Set this to false if you do not want scaled images to be re-oriented based on parsed EXIF data before they are uploaded.

Type:
Boolean
Default Value:
true

sendOriginal

Set this to false if you don't want to original file to be uploaded as well.

Type:
Boolean
Default Value:
true

sizes

An array containing size objects that describe scaled versions of each submitted image that should be generated and uploaded. A size object should usually contain a name String property (which will be appended to the file name of the scaled file), and must always contain a maxSize integer property. A type MIME string property is optional.

Type:
Array
Default Value:
[]

session

See the Initial File List feature page for more details.

customHeaders

Any additional headers you would like included with the GET request sent to your server. Ignored in IE9 and IE8 if the endpoint is cross-origin.

Type:
Object
Default Value:
{}

endpoint

If non-null, Fine Uploader will send a GET request on startup to this endpoint, expecting a JSON response containing data about the initial file list to populate.

Type:
String
Default Value:
null

params

Any parameters you would like passed with the associated GET request to your server.

Type:
Object
Default Value:
{}

refreshOnReset

Set this to false if you do not want the file list to be retrieved from the server as part of a reset.

Type:
Boolean
Default Value:
true

text

defaultResponseError

In the event of non-200 response from the server sans the 'error' property, this message will be passed to the 'error' event handler.

Type:
String
Default Value:
Upload failure reason unknown

fileInputTitle

The value for the title attribute attached to the <input type="file"> maintained by Fine Uploader for each upload button. This is used as hover text, among other things.

Type:
String
Default Value:
file input

sizeSymbols

Symbols used to represent file size, in ascending order.

Type:
Array
Default Value:
['kB', 'MB', 'GB', 'TB', 'PB', 'EB']

validation

acceptFiles

Used by the file selection dialog. Restrict the valid file types that appear in the selection dialog by listing valid content-type specifiers here. See docs on the accept attribute of the <input> element

Type:
Comma-delimited list of valid MIMEtypes
Default Value:
null

allowedExtensions

Specify file valid file extensions here to restrict uploads to specific types.

Type:
Array
Default Value:
[]

allowEmpty

Allow file size of 0 bytes

Type:
Boolean
Default Value:
false

itemLimit

Maximum number of items that can be potentially uploaded in this session. Will reject all items that are added or retried after this limit is reached.

Type:
Integer
Default Value:
0

minSizeLimit

The minimum allowable size, in bytes, for an item.

Type:
Integer
Default Value:
0

sizeLimit

The maximum allowable size, in bytes, for an item.

Type:
Integer
Default Value:
0

stopOnFirstInvalidFile

When true the first invalid item will stop processing further files.

Type:
Boolean
Default Value:
true

image.maxHeight

Restrict images to a maximum height in pixels (wherever possible).

Type:
Integer
Default Value:
0

image.maxWidth

Restrict images to a maximum width in pixels (wherever possible).

Type:
Integer
Default Value:
0

image.minHeight

Restrict images to a minimum height in pixels (wherever possible).

Type:
Integer
Default Value:
0

image.minWidth

Restrict images to a minimum width in pixels (wherever possible).

Type:
Integer
Default Value:
0

workarounds

Flags that enable or disable workarounds for browser-specific bugs.

iosEmptyVideos

Ensures all <input type='file'> elements tracked by Fine Uploader do NOT contain a multiple attribute to work around an issue present in iOS7 & 8 that otherwise results in 0-sized uploaded videos.

Type:
Boolean
Default Value:
true

ios8BrowserCrash

Ensures all <input type='file'> elements tracked by Fine Uploader always have a multiple attribute present. This only applies to iOS8 Chrome and iOS8 UIWebView, and is put in place to work around an issue that causes the browser to crash when a file input element does not contain a multiple attribute inside of a UIWebView container created by an iOS8 app compiled with and iOS7 SDK.

Type:
Boolean
Default Value:
false

ios8SafariUploads

Disables Fine Uploader and displays a message to the user in iOS 8.0.0 Safari. Due to serious bugs in iOS 8.0.0 Safari, uploading is not possible. This was apparently fixed in subsequent builds of iOS8, so this workaround only targets 8.0.0.

Type:
Boolean
Default Value:
true