jQuery.FileDrop.js

A simple way to add file drag-n-drop to your web projects

Fork on GitHub Download

FileDrop is made to be dead simple to use. At minimum all you need to do is select the element you want to be able to drop files onto, and then provide a function to loop over the array of returned files.

Like This: 
$('html').fileDrop(function(fileCollection){
    $.each(fileCollection, function(){
        console.log(this);
    });
});

Try It Out!

Drop some files anywhere on this page!

Also, open the console to see the file objects as you drop them! 
The file contents will be displayed over here

Options

You may either pass in a function to loop over the collection of file (as in the example above) or you may pass in an option object if you need to be more specific. All the possible options are below.

Name Type Default Value Description
onFileRead function null This option is required! You must provide a function to process the collection of file object that will be returned as the only argument. This function can optionally be the only argument passed if you do not need to specify any other options.
overClass string 'state-over' When files are dragged over the browser window, this is the CSS class that will be applied to the selected element or the element specified with the addClassTo option.
addClassTo jQuery selector string or object null This is the element that will have the CSS class set with the overClass option applied to it. By default whatever you select with jQuery to will also have addClassTo applied to it. Of course, you can specify a different element with this option if needed.
removeDataUriScheme boolean true When JavaScript reads the file data, it comes back as base64 encoded data which begins with something like 'data:text/plain;base64,'. When this option is enabled, this will be removed from the base64 string so that the pure base64 data can be processed or sent to a server. It is recommended to keep this option enabled unless you need to work with dropped images in JavaScript.
decodebase64 boolean false When JavaScript reads the file data, it comes back as base64 encoded data. Enabling this option will decode the base64 data into the raw file contents. This is useful for pure JavaScript applications where you might want to parse file contents directly in the browser. It is not recommended to use this option if you plan on sending the file contents to a server via AJAX.
Example Usage: 
$('#myElement').fileDrop({
    onFileRead : function(fileCollection){
        $.each(fileCollection, function(){
            //Do stuff with fileCollection here!
        });
    },
    overClass : 'my-custom-class',
    addClassTo : '#anotherElement',
    decodebase64 : true
});

File Objects

When implementing the onFileRead function, it needs to loop over the array of files that have been dropped onto the browser window. Each of the returned File Objects will have several properties on them.

Name Type Description
data string This is the actual data of the file. Depending on the options you set, this will be either a base64 encoded string, or the raw file contents.
lastModified Date object The date that the file was last modified on.
name string The file name.
size integer The size of the file, in bytes.
type string The MIME type of the file.
Example File Object with base64 encoded data 
{
    data: "/9j/4AAQSkCAgLCg … KKACiooooA//Z"
    lastModified: Tue Jul 30 2013 21:29:54 GMT-0500 (CDT)
    name: "fileName.jpg"
    size: 74196
    type: "image/jpeg"
}
Example File Object with decoded base64 data 
{
    data: "Hello World!"
    lastModified: Sat Aug 17 2013 15:04:20 GMT-0500 (CDT)
    name: "hello.txt"
    size: 12
    type: "text/plain"
}

Methods

Name Accepts Returns Description
$.removeUriScheme('...') string string This will remove the data URI scheme from the beginning on the base64 string. Data URI schemes look like "data:text/plain;base64,"
window.atob('...') base64 string string This will decode a base64 encoded string. This is built into most browsers, but this plugin also enables this feature on browsers that do not support it natively.
$.support.fileDrop N/A boolean Tells you if the browser natively supports file drag-n-drop. This does not give support to the browser, it only detects support.

If you need the flexibility of deciding when to base64 decode the file data, don't worry!

Let's say you have both the removeDataUriScheme and decodebase64 options set to false, and then you have a file dropped onto the page and it's data reads "data:text/plain;base64,SGVsbG8gV29ybGQh".

You can pass that string into the public method $.removeUriScheme('...'); and it will turn the above data string into "SGVsbG8gV29ybGQh" which is now just pure base64 encoded data. If you need to actually decode the base64 data manually, just pass it into window.atob('...');. This is native to most browsers, but this plugin will enable it for older browsers as well. After decoding you are left with the raw file contents, which in this case is Hello World!

Support

Not all browsers support file drag-n-drop, and this plugin does not magically give drag-n-drop support to browsers. BUT at least there's an easy way to test for this.
When you include this plugin on your page, just call $.support.fileDrop to find out if the browser supports file drag-n-drop or not. If so you can use this plugin, if not you will need to give your users other instructions.

Example: 
if($.support.fileDrop){
    $('html').fileDrop(function(fileCollection){
        $.each(fileCollection, function(){
            console.log(this);
        });
    });
}else{
    alert('Your browser does not support file drag-n-drop :(');
}

Drop Your Files Anywhere!