Table of Contents

Required Options

Plupload has only two required options: browse_button and url. The rest is optional. If any of these is missing, initialization will result in Error event with the code of plupload.INIT_ERROR.

browse_button

Required

Almost any DOM element can be turned into a file dialog trigger, but usually it is either a button, actual file input or an image. Value for the option can be either a DOM element itself or its id.

url

Required

Url of the server-side upload handler that will accept the files, do some security checks and finally move them to a destination folder. Might be relative or absolute.

Filters

filters

Default: {}

Plupload comes with several built-in filters that provide a way to restrict a selection (or perhaps an upload) of files that do not meet specific requirements. These are:

It is also possible to define custom file filters.

filters.mime_types

Default: []

By default any file type can be picked from file selection dialog (which is obviously a rarely desired case), so by supplying a mime_types filter one can constrain it to only specific file types.

For example to allow only images and zip archives:

filters: {
  mime_types : [
    { title : "Image files", extensions : "jpg,gif,png" },
    { title : "Zip files", extensions : "zip" }
  ]
}

title property will be used as a title for the filter, where supported.

Official format for the accept attribute, where one can supply comma-separated list of mime types, is also supported (but the former one is recommended):

filters: {
  mime_types : "image/*,application/zip"
}

Unfortunately browsers do not always interpret this option consistently (especially in html5 runtime). For example, no matter what, Firefox will still allow to select any file type by default and optionally provide a file filters at the bottom of the selection dialog. In addition to this there are differences in the interpretation of the accept attribute of input[type="file"] itself, for more information check: "Although I specify file extension in filters, I still cannot pick it up in file dialog or drag and drop, why?" entry from our FAQ.

filters.max_file_size

Default: 0 (unlimited)

By default, file of any size is allowed to the queue. But it is possible to constrain it from the top with the max_file_size filter. It accepts numeric or formatted string values, e.g.: 204800 or "204800b" or "200kb".

If violated, triggers Error event with the code of plupload.FILE_SIZE_ERROR.

filters.prevent_duplicates

Default: false

If set to true the Plupload will not allow duplicates. Duplicates are detected by matching file's name and size.

If violated, triggers Error event with the code of plupload.FILE_DUPLICATE_ERROR.

Control the Request

headers

A way to pass custom HTTP headers with each upload request. The option is simple set of key/value pairs of header names and their values.

  • Not supported by html4 runtime.
  • Requires special operational mode in case of flash and silverlight runtimes.

multipart

Default: true

Whether to send the file as multipart/form-data (default) or binary stream. The latter case is not supported by html4 and is a bit troublesome in flash runtime. It also requires a special care on server-side. Here's an excerpt from our bundled upload.php for example:

<?php
...
if (!$in = @fopen("php://input", "rb")) {
  die('{"jsonrpc" : "2.0", "error" : {"code": 101, "message": "Failed to open input stream."}, "id" : "id"}');
}
...
  • Not supported by html4 runtime.
  • flash runtime requires the file to be read in memory first.

multipart_params

Additional multipart fields to be passed along with each upload request. Each field can be represented by simple key/value pair or some nested arrays and/or objects. For example:

multipart_params: {
  one: '1',
  two: '2',
  three: '3',
  object: {
    four: '4',
    five: '5'
  },
  array: ['6', '7', '8']
}

max_retries

Default: 0 (no retries)

If max_retries is greater than 0, upload will be retried that many times every time there is plupload.HTTP_ERROR detected. Be it complete file or a single chunk.

Chunk

Plupload has a built-in support for chunking - file is split into chunks and uploaded part by part, and then reassembled back on the server. Obviously that requires some additional work on server side.

The whole concept of chunking might be a bit confusing - when you should use it and when you shouldn't, etc. We have the entry in our FAQ about this.

chunk_size

Default: 0 (disabled)

The size of each chunk in bytes. The value can be a number or a string with byte suffix, e.g.: 204800 or "204800b" or "200kb".

You can read more about the chunking and the way to handle it on server-side in our dedicated entry - here.

Client-Side Image Resize

resize

Disabled by default

Plupload can downsize the images on client-side, mainly to save the bandwidth. Perfect solution for thumbs, avatars and such. Currently not recommended for images sensible to quality drop. We are working to implement bilinear resampling algorithms, but they still have to come (scheduled for version 2.2).

More information about client-side image resizing can be found in a dedicated wiki entry.

resize.width

Defaults to original width of the image

The new width for the downsized image. If not specified will default to the actual width of the image.

resize.height

Defaults to original height of the image

The new height for the downsized image. If not specified will default to the actual height of the image.

resize.crop

Default: false

Whether to crop the image to exact dimensions, specified by width and height, or - not. Default is - not. By default image will be resized retaining its proportions. Enabled crop is good for thumbnails that frequently disregard the proportions at once.

resize.quality

Default: 90

This option is only applicable to JPEGs, since PNGs are lossless and are not subjected to quality cuts. The higher is quality the better the image looks, but the bigger its size is. It must said that quality can only be dropped and never improved. So this option must be used carefully.

quality option can be used in conjunction with the new width and height or separately. In the latter case, the dimensions of the image will stay the same, but the file size with high probability will noticeably decrease.

resize.preserve_headers

Default: true

Another option that is only applicable to JPEGs. Controls whether the meta headers, containing Exif, GPS or IPTC data, etc, should be retained after the downsize completes. By default meta headers are preserved, but you can set this to false if you do not require them and save some more bytes.

Drag&Drop Files from the Desktop

In addition to file picking, Plupload supports dragging and dropping the files from the desktop. In Chrome 21+ it also supports dragging and dropping of the whole folders. It is worth to mention that files are still subjected to filtering according to the rules defined in the filters option.

drop_element

Disabled by default

The DOM element to be used as the dropzone for the files, or folders (Chrome 21+). Can be an id of the DOM element or the DOM element itself, or an array of DOM elements (in the case of multiple dropzones). Currently supported only by html5 runtime (and this will probably never change).

Useful Options

multi_selection

Default: true

This option allows you to select multiple files from the browse dialog. It is enabled by default, but not possible in some environments and runtimes. For example iOS7 (being an ugly update in general) brought the buggiest Safari since like version 1.0, where selection of the multiple files doesn't trigger the onchange event at all (let us know if it is fixed by the time you are reading this). So we had to forcefully disable it there (#905). Also html4 runtime by its very nature is not compatible with multi_selection option being set to true, so it's disabled there as well.

required_features

By default Plupload will try to use the runtime that fits the requested configuration the best. But sometimes you might want to hint it to choose only a runtime that fulfills specific requirements and provides particular functionalities. That's where required_features option comes in handy.

required_features is an option of mixed type - it can be a comma-separated string of features to take into account. Or - an object of key/value pairs, where the key represents the required feature and the value must be fulfilled by the runtime in question. Or it can be simply set to true and then the configuration itself will be translated into a corresponding set of features that the selected runtime must have to fulfill the expectations. Without it Plupload will simply consider the options in the configuration (like chunk_size or resize) as optional - in other words fulfilled only when they can be fulfilled by the selected runtime. When required_features are set, runtimes that doesn't have appropriate capabilities will be simply ignored.

The list of supported features as well as the whole topic in more detail is available - here.

unique_names

Default: false

When set to true, will generate an unique file name for the uploaded file and send it as an additional argument - name. This argument can then be used by the server-side upload handler to save the file under that name.

Optional

runtimes

Default: "html5,flash,silverlight,html4"

Comma separated list of upload runtimes to try. In most cases you do not even need to care about this option. By default, Plupload will try what it thinks is best for your configuration. Or if there are no special requirements it will take html5 first and only if it fails proceed to flash or silverlight or legacy html4, until it finds a runtime that works. If none is compatible, Plupload will fail with the Error event of plupload.INIT_ERROR.

You only need to provide this option if you want to change the order in which runtimes will be tried, or want to exclude some of them at all.

file_data_name

Default "file"

Value of file_data_name will be used as the name for the file field in multipart request. So that in PHP, for example, you will be able to access it through: $*FILES["file"]. If for some reason you need it to be named differently, you can pass a different value for file_data_name.

container

Defaults to a parent node of browse_button

DOM element that will be used as a container for the Plupload html structures. By default an immediate parent of the browse_button element is used. If for some reason such behaviour is undesirable you can pass an id of a specific DOM element or the DOM element itself as the value for the container option.

Sometimes you might want to hide the browse_button after files are selected and some users tend to hide the parent container, which effectively hides the Plupload structures as well. For flash and silverlight runtimes this is equal to disabling, since due to security concerns those runtimes cannot not operate when they are not visible. In such cases better use disableBrowse() instead.

flash_swf_url

Default: "js/Moxie.swf"

The url of the Flash component, required by the flash runtime. It will fail, if the component is not found or cannot be loaded within a sane amount of time and Plupload will try the next runtime in the list. You do not need to set this option manually if you are using default file structure.

silverlight_xap_url

Default: "js/Moxie.xap"

The url of the Silverlight component, required by the silverlight runtime. It will fail, if the component is not found or cannot be loaded within a sane amount of time and Plupload will try the next runtime in the list. You do not need to set this option manually if you are using default file structure.

If this paragraph looks like a copy/paste of the flash_swf_url description it's because it - is.

Fork me on GitHub