• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!



Page history last edited by Aurélio A. Heckert 12 years, 1 month ago

type: widget

release: N/A

priority: none

status: in planning

documentation: N/A

demo: LABS




1 - Description:


A file uploader extends the default single file browse tool with to allow for a custom UI for providing feedback, the ability to upload multiple files at once and a real-time progress bar for upload feedback.


A few jQuery plugins provide all or some of this functionality:

https://github.com/blueimp/jQuery-File-Upload (demo: http://aquantum-demo.appspot.com/file-upload)




http://jquery.webunity.nl/jQuery.uploader/landing (this is the latest version of the plugin that was documented on the jQuery site at http://docs.jquery.com/UI/Uploader)




http://www.plupload.com/index.php Has a jQuery widget, drag and drop support, multiple file upload and more.

http://plugins.jquery.com/project/fileinput - jQuery UI widget replacement for form file inputs. Works with ThemeBuilder and custom styling.

https://github.com/blueimp/jQuery-File-Upload (demo: http://aquantum-demo.appspot.com/file-upload )


2 - Visual Design:





3 - Functional Specifications/Requirements:


All functionalities need to work independent to each other


  • File input or Form replacement
    • this should be the basic functionality
  • Ajax
    •  upload file ( or files ) without leaving the page
  • Queue 
    • provide an option so that a user could select multiple files and upload them at once
  • Transporter
    • provide different ways to allow controlled uploading


How to achieve the functionalities


File input replacement

This should be optional, the user may use any object as a uploader ( images, links etc ). Since we can't trigger a click event for a file input we have to improvise. We need to create a file input right near the selector, because the file input might be used in a form. The thing that all the plugins have in common is that it creates a file input at the cursor's position when it hovers the element. 


This is pretty easily, we must get the object's coordinates ( offset left, offset top, width and height ) and when the event meets the conditions display the file input. But we must be careful because the button may change it's position or dimension. So it's better to take in consideration a method that would recalculate the coordinates based on the current position and dimension.


Form replacement

A serious webdeveloper must, at lest, consider graceful degradation methods to ensure the accessibility of a website. As we are proposing, the jQueryUI FileUploader will do all the work alone. It is not the same as an input element, it is a powered form element!


Converting a form into a FileUploader we get some useful information about the application, we may use the non file input fields as a template to collect meta-data for each file, and if something fails the user still can to upload his files.


For each selected file a box with it's name will be created, based on the default uploader template or other provide by the user in fileBoxTemplate option. If the option autoUpload is false, all form fields, but the input file and the submit, will be cloned inside the box to be filled before the uploading start. That data will be sent in a "multipart/form-data" form with the file. If the option autoUpload is true, the form will be cloned with a hidden field named with the uploadIdFieldName option value. That will add the uploadIdFieldName with uploadId as value on the multipart-form when uploading the file (without user interaction) and the same on the meta-data form as a hidden input, to be sent when the user fill the fields and press a "save" button. That will enable the server application to recognize the relation between the uploaded file and the meta-data received on different submissions. The meta-data added by the extra fields will be visible on the metaData attribute of the FileToUpload object while it exists, independent of the autoUpload is value. All data attached on metaData attribute will be sent, so the page code may add more informations there without need a new the form field.




The user must not need to be redirected to submit files, that allows to collect meta-data from the files while uploading, or use the FileUploader when is needed to attach files to a article being created. Examples to illustrate:

  • Youtube video uploader: allows the user to send how many videos that wants and open a meta-data form to describe each uploading video.
  • General article publisher: while writing the user may want to add some pictures to the article, he may click on add files on the side-box and automatically receive the published image reference (to add to the rich text editor) when the upload is ended.




The FileUploader may work with autoUpload enabled or not. autoUpload enable means that will automatically start the file upload when the user select it. In the other end, the method send() must be called. In both cases we'll have a "upload list" a list of FileToUpload objects, where each one refers to a selected file, and that order is the same as the user selection order, but may be changed as any array. The list will let to easily handle the selected files, to upload each file in a different connection, to a better progress control and to easily add some meta-data. The FileUploader will always respect the "upload list" order to build a queue, but will try to send the files in parallel, the next file must not to wait the finish of the precursor to be sent.



  • Flash 
    Allows to track the progress on old browsers (must be supported?) 

  • XMLHttpRequest

    Must be the default transporter

  • IFrame

    For old browsers without XMLHttpRequest with FormData support


API Interface



  • disabled - Boolean - default: false
  • submitURL - String - if undefined, tries to get the form's "action" attribute.
  • submitMethod - String - if undefined, tries to get the form's "method" attribute.
  • maxFiles - Integer - default: 0 means no limit on the number of selected files to upload
  • maxFileSize - KB in Float - default: 0 means no limit per selected file
  • maxTotalFileSize - KB in Float - default: 0 means no limit for the sum of selected files
  • mimeTypes - Array of Strings - default null (define a list of accepted file types to upload)
  • fileBoxTemplate - jQuery.template reference - a default template is defined by the FileUploader
  • autoUpload - Boolean - default: false (if true start uploading when the file is selected)
  • uploadIdFieldName - string - default: "uploadid"
  • globalProgressbar - element reference - default: null (if referenced and not converted to jQueryUI Progressbar, that may be done using default values. if defined that must be auto updated by the fileuploader, if not this fileuploader will not have a progressbar)
  • showEachFile - Boolean - default: true (will show the name, progress and cancel button for each file)
  • palallelLimit - Integer - default: 5 - The other files on the upload list still on queue until no one finishes. This will help to not explode the server connections when uploading several files.



  • option - .fileuploader( "option" , optionName , [value] )
  • addFile - .fileuploader( "addFile" , fileName , fileData ) - useful to save work done on the web using canvas or another bowser technology. Must support base64 as fileData.
  • listFiles - .fileuploader( "listFiles" ) - return an array of FileToUpload objects.
  • send - .fileuploader( "send" ) - start to upload all files in the upload list if autoUpload is false.



  • progress( total, uploaded ) - the global upload progress
  • fileAdded( FileToUpload ) - with "showEachFile = false" allow to create an unique UI for each uploading file, or allow to verify file details before the upload.
  • fileRemoved( uploadId, fileName )
  • started()
  • complited( serverResponse )
  • failed( error )


The FileToUpload object


  • uploadId - String (a hash to identify the file when that must be refereed on future submitting)
  • fileName - String
  • fileData
  • fileSize - KB in Float.
  • progress - Float inside [0, 1] range.
  • progressElement - jQueryUI widget reference, if there is one.
  • widget - the jQueryUI fileuploader widget reference, were that file was added.
  • metaData - a hash of data related to the file, to be sent as "multipart/form-data".


  • send() - upload the file to the server.
  • destroy() - remove the file from the uploat list.


  • destroying() - trigged before the FileToUpload object remotion from list. Returning false cancels the destruction.
  • progress( total, uploaded ) - the file upload progress
  • started()
  • complited( serverResponse )
  • failed( error )



4 - Markup & Style:


     4.1 Initial markup examples


     (Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )


     4.2 Recommended transformed HTML markup


     (The HTML markup structure and classes that will be used by the scripts in the enhanced version) 


     4.3 Accessibility recommendation


    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 


     4.4 CSS & Theme


    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 



5 - Latest version of plugin:


(Link to the latest version in the jQuery UI trunk here)



6 - Open issues being discussed


(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)



Comments (Show all 62)

Jaggi said

at 7:17 am on Nov 25, 2009

@Basit look at the top of the page in the right area, theres a area called " sidebar" with all the links you need.

Basit said

at 9:12 am on Nov 25, 2009

@Jaggi thanks for the tip. i noticed the uploader on UI/uploader documentation is not completely free and opensource (http://docs.jquery.com/UI/Uploader). it needs a flash file to work properly and the guy who created it, he is charging money for it lol, cause he said it was hard writing 2000 lines, so he has to charge it. i recommand jquery guys to remove that uploader from documentation. i will definitely work on the uploader and opensource the flash file also, so everyone can access and update it from github. anyway, thanks again. ill get on it and launch the plugin at http://basit.me

Yanick said

at 9:35 am on Nov 25, 2009

Like I said, if you want to use a flash component as backend (at least until HTML support the same features natively), take a look at SWFUpload. It is free, signed, and have been tested for a while now by many people. It does not have an interface, so it is controlled strictly via handlers and functions through Javascript. (ie: opening file; swfUploader.browse(); this will open the flash "open file" dialog with multiselection capabilities, and for each selected file, a callback will be invoked with the fileInfo as argument (size, name, etc.) I guess the flash file could be inserted into the DOM automatically also, hence users would only require the ui-upload.js plugin (or even the single packed ui.js file) and everything would work straight out of the box. Writing the UI from the given specifications with SWFUpload is a breeze! And no server side scripts required. I'm pushing this idea because, so far, everything that has been spoken is fulfilled by SWFUpload. If not, I would like to know why? :)

Basit said

at 10:30 am on Nov 25, 2009

well everything is possible, but response back from the backend is also must, some people like myself uses for checking the responses and errors and limitations. but response back should be optional and everything should work out of the box and everything should be changeable also. no limitations and no restrictions.

Yanick said

at 11:03 am on Nov 25, 2009

getting server side state can be done with the onComplete event callback from the SWFUpload component...

Scott González said

at 9:45 am on Nov 25, 2009

Thanks for pointing out that documentation page, I've moved it to Plugins/Uploader so there is no longer any content under UI/Uploader since that was not a UI plugin.

Gilles said

at 3:36 am on Jan 12, 2010

Basit that is not fair; i am not charging any money for the flash file, all can be downloaded and is documented right off my site. I only asked (past tence) money for the source which is fair i guess. It took a lot of time and thinking to get it right.

--> I fully open sourced the project and added it to SVN some time ago; http://jquery-ui.googlecode.com/svn/branches/labs/uploader/ <--

So the full actionscript code is there; sitting to be 'checked' by the UI team but as Scott said; it is not a prio right now. I am using my own plugin allready on my own projects.

Scott González said

at 9:44 am on Nov 25, 2009

As Jaggi said, there are links to some of this information in the sidebar. However, there's a lot of missing content (I know because I wrote them). The relevant pages are:

For coding standards, read the Coding-standards page and just look through some of our existing code (dialog, progressbar and position should be good examples). Feel free to also just ask any questions on the jquery-ui-dev mailing list. The hardest part will be getting specs for this plugin because the team is in a crunch for the 1.8 release right now. You can start putting together some specs on this page and then just ask for feedback, just be aware that it may be a bit of a slow process. The more minimal the API is, the more likely it is to be approved.

Basit said

at 10:34 am on Nov 25, 2009

thanks for the links. ya ill write the specs and go from there. but so far i know myself and jquery team, its most likely will be approved. anyway thanks and ill write specs soon.

Basit said

at 5:04 am on Nov 26, 2009

there are few issues i wanted to talk about with you guys. there are few options i was thinking to add as per requirement from above image. adding an uploader on a file browse should not need an third party plugin (flash) in order to work, simply with $('input').uploader(); should start working instantly. but there is issue on progress bar. in order to have real time progress bar we need flash or get it done from backend and knowing that we cant put must require the third party, so the only way to do progress bar is on sent the request (50% complete) and on receiving the request (+50% complete) done, so that is 100%. if you guys want me to do it like that, then thats fine, we can do that, but if not, then share your thoughts how you want the progress bar to be achieved in the uploader? obviously i havent started to code, but im just planning first and then put all the options and requirement and then start building. anyway waiting for answers from you guys :).

Yanick said

at 9:30 am on Nov 26, 2009

Even when using flash, the code can still be $('selector').upload(); and the plugin can add the embedded flash player dynamically. Or it can simply rely on the server side to provide feedback. My opinion on this is this :

Pros to use flash for the plugin (temporarily until HTML supports file upload progress natively) :
- if flash is not available, the default input file will act normally (no progress)
- do not depend on server side at all and respect the 100% client side nature of JQuery
- increase the standard across browsers (some minor issues between OS and flash, but they are minor, and we can still degrade it to the HTML element only if needed)

And the cons:
- depends on flash
- the onProgress event with flash does not work at all on some OS and defeat the purpose of using flash, less multiple file selection capabilities
- flash use it's own session cookie when transferring files. This can be problematic for sites that require authentication when uploading files. A solution would be to fire a normal http request right after to tell the server that the specified file belongs to which user, but can be an undesirable process.

Yanick said

at 9:31 am on Nov 26, 2009

"Flash-less" solutions rely on server side scripts to handle the request, but PHP has still not provided good support for it, and other solutions (a la Google) requires Python. While Python is installed on most web servers (Linux), it is not desirable to couple JQuery with a server side script. At least I'm strongly against it.

Flash, on the other hand, is a temporary solution that works "well" on all major browsers, and should be able to degrade gracefully (like SWFUpload). The UI for the widget should be the same regardless if flash works or not. If it works, the normal behavior will be shown, with progression feedback. If not, the plugin should rely on other methods, perhaps an hidden iframe, to provide the necessary mecanism and fire, at least, the onComplete event and download the next. If all fails, the plugin could simply add the input file element, and wait for the form to be POSTed and processed as a standard form.

I know using flash is a reluctant idea, but none so far proposed a solution otherwise, or actually debated on the subject.

Scott González said

at 11:11 am on Nov 26, 2009

The project does not share your stance on not coupling plugins with server side scripts. Such a restriction would make several plugins very difficult or impossible to implement. Honestly, for many situations I'd rather see a server side solution than a flash solution. Server side solutions take advantage of the open web.

Gilles said

at 3:45 am on Jan 12, 2010

Well i have thought about coupling it with a few other things like:
- Browserplus (yahoo tech, which would make drag & drop uploads possible) mainly improvement on the client side
- Serverside CGI script (limit parralel uploads, but gives feedback)
- And flash off course

But; it is mainly a choice that the project team has to make; are you willing to implement a plugin depending (for a part) on Flash; just like EXT and YUI allready did? That is the main question holding things back really. I have been discussing this plugin with paul long before this wiki was here, so just to give you an idea on how long i have been working on it ;)

Scott González said

at 11:09 am on Nov 26, 2009

Faking 50% and then reporting 100% on completion sounds fine. The plugin should be built in a way to allow another script to be loaded that adds flash support to the plugin to get a more accurate progress.

Basit said

at 9:46 am on Nov 26, 2009

well so far i know, flash is must for two things. one is progress bar and second is the multiple instance (able to select 10/100 files at once).

ya i agree, we should not rely from server side or from flash, but flash can be used, if user wants it for using multi-instance or progress bar. but if flash is not used, then the solution i gave for 50% on trigger and 50 on receiving a response from client, can be good thing. i think that would be best solution for us, without relying on third party.

Yanick said

at 11:26 am on Nov 26, 2009

What about, then, using an adapter?

ie: $('selector').upload({ adapter: 'flash' }); // 'flash'=Flash based uploader, 'ajax'=server side ajax based uploader, null=standard uploader

Common options would be event callbacks, and other settings (max file count, etc.), and depending on the adapter, also have other options:

ex: $('selector').uploader({ adapter: 'ajax', uploadUrl: '/path/to/upload', progressUrl: '/path/to/progress', onProgress: callback1, onComplete: callback2, .... });
ex: $('selector').uploader({ adapter: 'flash', uploadUrl: '/path/to/upload', multiselect: true, fileCount: 10, onProgress: callback1, onComplete: callback2, .... });

webwurst said

at 7:43 am on Sep 6, 2010

I added Plupload to the link list. Seems quiet nice, although i don't like the ui. It lacks features like auto-start or limiting the amount of files, i think, but has many others.

Jaggi said

at 4:21 am on Sep 9, 2010

Alexandre Magno said

at 8:22 am on Jan 28, 2011

Hello, I'm the author of jqswfupload, one of the plugins at the link list. I'm not maintaining this plugin anymore, and I start to rewrite a new one using jQuery-UI pattern. It can be found at https://github.com/alexanmtz/jQuery-ui-upload.

I use the swfupload library cause it's already stable and has all the flash communication and make me focus in what really matters: the jQuery-ui interface. The biggest problem was make fully unit testable, but I make what I could to have minimum tests. I thing is very usefull use a stable multi-upload library rather that rewrite a new one.

They have some of features listed at this page, besides that it has a new concept of file group to control limits of filesize and amount of files allowed. So you can make this at plugin options:

url: '/upload/',
rules: {
'image' : {
'fileTypes' : ['jpeg', 'jpg', 'png'],
'limit' : 6,
'size' : '200 KB'
'video' : {
'fileTypes' : ['mov'],
'limit' : 1,
'size' : '20 MB'

You can see a demo at: http://www.alexandremagno.net/jquery-ui-upload/demo.html

I hope that the plugin can be useful and I wish to have feedback to improvet it and maybe be the official jQuery uploader widget.

Scott González said

at 8:49 am on Jan 28, 2011

It's great to hear that you'd like to work on the official upload widget. However, as mentioned above, the widget has to work without flash and then flash can be layered on for more complete functionality. If you're interested in tackling this, the first step would be to outline the API in section 3 of this page.

Also, please do not name your plugin jquery.ui.upload.js or include the official jQuery UI header in your file. This is very misleading and inaccurate as the plugin is not copyright the jQuery UI authors and is not officially part of jQuery UI. The only time this is acceptable is when the source files come from the jquery-ui repository.

Alexandre Magno said

at 12:44 pm on Jan 28, 2011

Hey Scott,

Sorry for the mistakes, It was lack of knowledge about how works this procedures. I take out the jQuery UI header as you requested. About the name, you really see any problem cause the name of the official plugin will be fileUploader? I follow the convention because I'm using the pattern of jQuery UI so it's fair follow his convention.

Well, about the section 3 I understand, but the flash it's not just for progress, a multiple file selection box it's only possible using flash. What I thing to implement for next release it's a link like "Are you having trouble with this upload? try the common upload instead". It's a UI pattern already used by a lot of upload systems like flickr, facebook, wordpress etc and this way the plugin call destroy method and a normal browser upload it's shown.

What you think about the concept of file groups to better handler group limits? It's because in my experience with upload plugins you just can say that formats x, y, z has 20kb of limit for example, but I would like to use in a way that "the types x, y that are images can have 20kb of limit".

one more time sorry for inconvenience...

Scott González said

at 1:52 pm on Jan 28, 2011

The problem with the filename and the name of the widget is that jquery.ui indicates that it's part of jQuery UI, which it's not (though it can be in the future).

The plugin should be built to handle whatever is possible with just HTML/CSS/JavaScript. It should allow extending or creating a new plugin on top of it in order to add additional features. See the autocomplete demos as an example (multiple support is built on top, combobox is built on top, etc.).

As far as file groups, I'd want to see it in the context of the full API before making any decisions.

Alexandre Magno said

at 12:23 pm on Feb 1, 2011

I changed the name as you said to the old plugin name (jqswfupload). I understand your point of view and I will make the necessary changes to fit in this context.

Jason Shimkoski said

at 9:45 am on Mar 1, 2011

Hello all,

I'm new here! Just wanted to let you know I added a plugin to the bottom of the list in section 1, Description.

It is a jQuery UI widget that acts as a replacement for form file inputs. It is completely compatible with ThemeRoller and the user can custom style it to their liking if they please.

It uses mouse tracking instead of image replacement so it is a bit more flexible than other options.

It does not use the UI namespace (I'm using shimmy).

Check it out and let me know what you think.


Pierre.H A said

at 1:33 pm on Mar 22, 2011

http://aquantum-demo.appspot.com/file-upload fit most of the requirements

Jez said

at 2:06 pm on Mar 28, 2011

I'm surprised this isn't beyond planning stage by now. Many modern browsers support "progress" updates via XHR and so we could make this jQuery UI plugin actually Flash-free and just use pure AJAX for updating progress. Can we get a list of browsers that support XHR file upload "progress" events? I'm pretty sure Firefox 3.6 and 4 do. Here's an example of jQuery code that utilizes this for a file upload control:

Michael Lang said

at 5:00 pm on Apr 9, 2011

I found a jquery plugin with an MIT license that uses just HTML5 and javascript. The HTML5 is a progressive enhancement. It works on lots of browsers.
* Google Chrome - 7.0, 8.0, 9.0, 10.0
* Apple Safari - 5.0
* Mozilla Firefox - 3.6, 4.0
* Opera - 10.6, 11.0
* Microsoft Internet Explorer 6.0, 7.0, 8.0, 9.0

demo: http://aquantum-demo.appspot.com/file-upload

source and docs: https://github.com/blueimp/jQuery-File-Upload

Jez said

at 4:31 am on May 16, 2011

Very nice find, Michael. I think jQuery UI's file uploader control should be something like this.

blueimp said

at 9:07 am on May 16, 2011

Hi, I've just updated the aforementioned jQuery File Upload plugin.
It's now based on jQuery UI Widget, with extensive use of jQuery Deferreds and a new Iframe AJAX Transport module.
I still need to update the documentation to reflect the changes of this new version.

Jez said

at 10:00 am on May 16, 2011

Nice going, blueimp! Still no IE/Opera upload progress support?

Jez said

at 11:09 am on May 16, 2011

Another question, blueimp. Is it possible to make your plugin only support a single file upload (still with progress bar etc.), rather than multiple files?

blueimp said

at 1:03 pm on May 16, 2011

Opera has global progress support in the way that after each Iframe Transport upload, the file size can be reported since Opera supports the File API in the latest browser versions.
IE has very limited global progress support in the way that each Iframe Transport upload is weighed the same and reported when done.

Of course, you can use the plugin for single file uploads as well.
The plugin itself is modular, there is a basic version (jquery.fileupload.js) without user interface that provides an upload API and multiple callback hooks.
The UI version (jquery.fileupload-ui.js) is geared towards multiple file uploads, but can be extended to fit into a single file uploader as well (there is even an option "maxNumberOfFiles").

Jez said

at 3:38 am on May 18, 2011

blueimp: OK... your demo page at http://aquantum-demo.appspot.com/file-upload

... says that Opera has no support for upload progress, in Browser support note 2. Is that comment worth removing?

Jez said

at 3:41 am on May 18, 2011

Looks like the screwed-up formatting of that last comment means that when you click on this Add a comment textbox it tries to nagivate to a URL! Boy oh boy... they should proabably use MediaWiki.

(please ignore this comment)

Jez said

at 3:42 am on May 18, 2011

And looks like my last comment fixed the problem.

(please ignore this comment too)

Aurélio A. Heckert said

at 12:23 pm on Dec 22, 2011

Sorry this humble question, but... where is this plugin been implemented?
Is this https://github.com/blueimp/jQuery-File-Upload ? That is not clear on the description.
Why that is not here: https://github.com/jquery/jquery-ui/tree/master/ui ?

Richard D. Worth said

at 12:36 pm on Dec 22, 2011

This plugin is not currently in development by the jQuery UI team. That's why the status at the top of this page is 'in planning' not 'in development'. Any links you find are work by individuals which we're happy to collect here as it will aid in the planning process (and development, once it starts). This plugin is on the roadmap for development in the 2.0 release cycle: http://wiki.jqueryui.com/w/page/12138038/Roadmap . A branch for it in the jquery-ui github repo may be created at that time, but that would be after the 1.9 final release.

Aurélio A. Heckert said

at 3:30 pm on Dec 22, 2011

Thanks for clarifying Richard!
So... The natural path is to merge some good started work, like the blueimp's plugin into jQueryUI or you will probably start a new from the scratch?
Sorry my question, i don't know the history or other jQueryUI components, but i want help on this.

Richard D. Worth said

at 3:56 pm on Dec 22, 2011

There are eleven such plugins (listed as reference) we may draw inspiration from, once we get to that point. More than likely none of them will be ideal enough as a wholesale direct starting point, just judging from past experience (not a criticism of any particular plugin, as I haven't looked). But we'll take whatever good we can get from them, and give credit where due. As an example, the Autocomplete widget today in jQuery UI was built based on the experience of Jörn (a jQuery UI dev lead) having built and supported an autocomplete plugin for years. But the UI plugin bears almost no resemblance to the original. Another example is http://wiki.jqueryui.com/w/page/35122722/Grid-OtherGrids

You don't have permission to comment on this page.