Using the File API, which was added to the DOM in HTML5, it's now possible for web content to ask the user to select local files and then read the contents of those files. This selection can be done by either using an HTML <input>
element or by drag and drop.
If you want to use the DOM File API from extensions or other browser chrome code, you can; however, note there are some additional features to be aware of. See Using the DOM File API in chrome code for details.
Accessing selected file(s)
Consider this HTML:
<input type="file" id="input">
The File API makes it possible to access a FileList
containing File
objects representing the files selected by the user.
If the user selects just one file, it is then only necessary to consider the first file of the list.
Accessing one selected file using a classical DOM selector:
var selectedFile = document.getElementById('input').files[0];
Accessing one selected file using a jQuery selector:
var selectedFile = $('#input').get(0).files[0]; var selectedFile = $('#input')[0].files[0];
If you get a "files is undefined
" error: you didn't select the right HTML element, forgetting that a jQuery selector returns a list of matched DOM elements. Get the DOM element to call the "files
" method on it.
Accessing selected file(s) on a change event
It is also possible (but not mandatory) to access the FileList
through the change
event:
<input type="file" id="input" onchange="handleFiles(this.files)">
When the user selects a file, the handleFiles()
function gets called with a FileList
object containing File
objects representing the files selected by the user.
If you want to let the user select multiple files, simply use the multiple
attribute on the input
element:
<input type="file" id="input" multiple onchange="handleFiles(this.files)">
In this case, the file list passed to the handleFiles()
function contains one File
object for each file the user selected.
Dynamically adding a change listener
If your input field was created using a JavaScript library such as jQuery, you'll need to use EventTarget.addEventListener()
to add the change
event listener, like this:
var inputElement = document.getElementById("input"); inputElement.addEventListener("change", handleFiles, false); function handleFiles() { var fileList = this.files; /* now you can work with the file list */ }
Note that in this case, the handleFiles()
function itself is the event handler, unlike previous examples where it was called by an event handler which passed it a parameter.
Getting information about selected file(s)
The FileList
object provided by the DOM lists all of the files selected by the user, each specified as a File
object. You can determine how many files the user selected by checking the value of the file list's length
attribute:
var numFiles = files.length;
Individual File
objects can be retrieved by simply accessing the list as an array:
for (var i = 0, numFiles = files.length; i < numFiles; i++) { var file = files[i]; .. }
This loop iterates over all the files in the file list.
There are three attributes provided by the File
object that contain useful information about the file.
name
- The file's name as a read-only string. This is just the file name, and does not include any path information.
size
- The size of the file in bytes as a read-only 64-bit integer.
type
- The MIME type of the file as a read-only string or
""
if the type couldn't be determined.
Example: Showing file(s) size
The following example shows a possible use of the size
property:
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>File(s) size</title> <script> function updateSize() { var nBytes = 0, oFiles = document.getElementById("uploadInput").files, nFiles = oFiles.length; for (var nFileId = 0; nFileId < nFiles; nFileId++) { nBytes += oFiles[nFileId].size; } var sOutput = nBytes + " bytes"; // optional code for multiples approximation for (var aMultiples = ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"], nMultiple = 0, nApprox = nBytes / 1024; nApprox > 1; nApprox /= 1024, nMultiple++) { sOutput = nApprox.toFixed(3) + " " + aMultiples[nMultiple] + " (" + nBytes + " bytes)"; } // end of optional code document.getElementById("fileNum").innerHTML = nFiles; document.getElementById("fileSize").innerHTML = sOutput; } </script> </head> <body onload="updateSize();"> <form name="uploadForm"> <p><input id="uploadInput" type="file" name="myFiles" onchange="updateSize();" multiple> selected files: <span id="fileNum">0</span>; total size: <span id="fileSize">0</span></p> <p><input type="submit" value="Send file"></p> </form> </body> </html>
Using hidden file input elements using the click() method
Starting in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1), you can hide the admittedly ugly file <input>
element and present your own interface for opening the file picker and displaying which file or files the user has selected. You can do this by styling the input element with display:none
and calling the click()
method on the <input>
element.
Consider this HTML:
<input type="file" id="fileElem" multiple accept="image/*" style="display:none" onchange="handleFiles(this.files)">
<a href="#" id="fileSelect">Select some files</a>
The code that handles the click
event can look like this:
var fileSelect = document.getElementById("fileSelect"), fileElem = document.getElementById("fileElem"); fileSelect.addEventListener("click", function (e) { if (fileElem) { fileElem.click(); } e.preventDefault(); // prevent navigation to "#" }, false);
You can style the new button for opening the file picker as you wish.
Using a label element to trigger a hidden file input element
To allow opening the file picker without using JavaScript (the click() method), a <label>
element can be used.
Consider this HTML:
<input type="file" id="fileElem" multiple accept="image/*" style="display:none" onchange="handleFiles(this.files)">
<label for="fileElem">Select some files</label>
There is no need to add JavaScript code to call fileElem.click()
. Also in this case you can style the label element as you wish.
Selecting files using drag and drop
You can also let the user drag and drop files into your web application.
The first step is to establish a drop zone. Exactly what part of your content will accept drops may vary depending on the design of your application, but making an element receive drop events is easy:
var dropbox; dropbox = document.getElementById("dropbox"); dropbox.addEventListener("dragenter", dragenter, false); dropbox.addEventListener("dragover", dragover, false); dropbox.addEventListener("drop", drop, false);
In this example, we're turning the element with the ID dropbox
into our drop zone. This is done by adding listeners for the dragenter
, dragover
, and drop
events.
We don't actually need to do anything with the dragenter
and dragover
events in our case, so these functions are both simple. They just stop propagation of the event and prevent the default action from occurring:
function dragenter(e) { e.stopPropagation(); e.preventDefault(); } function dragover(e) { e.stopPropagation(); e.preventDefault(); }
The real magic happens in the drop()
function:
function drop(e) { e.stopPropagation(); e.preventDefault(); var dt = e.dataTransfer; var files = dt.files; handleFiles(files); }
Here, we retrieve the dataTransfer
field from the event, pull the file list out of it, and then pass that to handleFiles()
. From this point on, handling the files is the same whether the user used the input
element or drag and drop.
Example: Showing thumbnails of user-selected images
Let's say you're developing the next great photo-sharing website and want to use HTML5 to display thumbnail previews of images before the user actually uploads them. You can establish your input element or drop zone as discussed previously and have them call a function such as the handleFiles()
function below.
function handleFiles(files) { for (var i = 0; i < files.length; i++) { var file = files[i]; var imageType = /^image\//; if (!imageType.test(file.type)) { continue; } var img = document.createElement("img"); img.classList.add("obj"); img.file = file; preview.appendChild(img); // Assuming that "preview" is the div output where the content will be displayed. var reader = new FileReader(); reader.onload = (function(aImg) { return function(e) { aImg.src = e.target.result; }; })(img); reader.readAsDataURL(file); } }
Here our loop handling the user-selected files looks at each file's type
attribute to see if it's an image file (by doing a regular expression match on the string "image.*
"). For each file that is an image, we create a new img
element. CSS can be used to establish any pretty borders or shadows and to specify the size of the image, so that doesn't need to be done here.
Each image has the CSS class obj
added to it, making it easy to find in the DOM tree. We also add a file
attribute to each image specifying the File
for the image; this will let us fetch the images for actual upload later. We use Node.appendChild()
to add the new thumbnail to the preview area of our document.
Next, we establish the FileReader
to handle asynchronously loading the image and attaching it to the img
element. After creating the new FileReader
object, we set up its onload
function and then call readAsDataURL()
to start the read operation in the background. When the entire contents of the image file are loaded, they are converted into a data:
URL which is passed to the onload
callback. Our implementation of this routine sets the img
element's src
attribute to the loaded image which results in the image appearing in the thumbnail on the user's screen.
Using object URLs
Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) introduces support for the DOM window.URL.createObjectURL()
and window.URL.revokeObjectURL()
methods. These let you create simple URL strings that can be used to reference any data that can be referred to using a DOM File
object, including local files on the user's computer.
When you have a File
object you'd like to reference by URL from HTML, you can create an object URL for it like this:
var objectURL = window.URL.createObjectURL(fileObj);
The object URL is a string identifying the File
object. Each time you call window.URL.createObjectURL()
, a unique object URL is created even if you've created an object URL for that file already. Each of these must be released. While they are released automatically when the document is unloaded, if your page uses them dynamically you should release them explicitly by calling window.URL.revokeObjectURL()
:
window.URL.revokeObjectURL(objectURL);
Example: Using object URLs to display images
This example uses object URLs to display image thumbnails. In addition, it displays other file information including their names and sizes.
The HTML that presents the interface looks like this:
<input type="file" id="fileElem" multiple accept="image/*" style="display:none" onchange="handleFiles(this.files)"> <a href="#" id="fileSelect">Select some files</a> <div id="fileList"> <p>No files selected!</p> </div>
This establishes our file <input>
element as well as a link that invokes the file picker (since we keep the file input hidden to prevent that less-than-attractive user interface from being displayed). This is explained in the section Using hidden file input elements using the click() method, as is the method that invokes the file picker.
The handleFiles()
method follows:
window.URL = window.URL || window.webkitURL; var fileSelect = document.getElementById("fileSelect"), fileElem = document.getElementById("fileElem"), fileList = document.getElementById("fileList"); fileSelect.addEventListener("click", function (e) { if (fileElem) { fileElem.click(); } e.preventDefault(); // prevent navigation to "#" }, false); function handleFiles(files) { if (!files.length) { fileList.innerHTML = "<p>No files selected!</p>"; } else { fileList.innerHTML = ""; var list = document.createElement("ul"); fileList.appendChild(list); for (var i = 0; i < files.length; i++) { var li = document.createElement("li"); list.appendChild(li); var img = document.createElement("img"); img.src = window.URL.createObjectURL(files[i]); img.height = 60; img.onload = function() { window.URL.revokeObjectURL(this.src); } li.appendChild(img); var info = document.createElement("span"); info.innerHTML = files[i].name + ": " + files[i].size + " bytes"; li.appendChild(info); } } }
This starts by fetching the URL of the <div>
with the ID fileList
. This is the block into which we'll insert our file list, including thumbnails.
If the FileList
object passed to handleFiles()
is null
, we simply set the inner HTML of the block to display "No files selected!". Otherwise, we start building our file list, as follows:
- A new unordered list (
<ul>
) element is created. - The new list element is inserted into the
<div>
block by calling itselement.appendChild()
method. - For each
File
in theFileList
represented byfiles
:- Create a new list item (
<li>
) element and insert it into the list. - Create a new image (
<img>
) element. - Set the image's source to a new object URL representing the file, using
window.URL.createObjectURL()
to create the blob URL. - Set the image's height to 60 pixels.
- Set up the image's load event handler to release the object URL since it's no longer needed once the image has been loaded. This is done by calling the
window.URL.revokeObjectURL()
method and passing in the object URL string as specified byimg.src
. - Append the new list item to the list.
- Create a new list item (
Here is a live demo of the code above:
Example: Uploading a user-selected file
Another thing you might want to do is let the user upload the selected file or files (such as the images selected using the previous example) to a server. This can be done asynchronously very easily.
Creating the upload tasks
Continuing with the code that built the thumbnails in the previous example, recall that every thumbnail image is in the CSS class obj
with the corresponding File
attached in a file
attribute. This allows us to select all of the images the user has chosen for uploading using Document.querySelectorAll()
, like this:
function sendFiles() { var imgs = document.querySelectorAll(".obj"); for (var i = 0; i < imgs.length; i++) { new FileUpload(imgs[i], imgs[i].file); } }
Line 2 fetches a NodeList
, called imgs
, of all the elements in the document with the CSS class obj
. In our case, these will be all of the image thumbnails. Once we have that list, it's trivial to go through it and create a new FileUpload
instance for each. Each of these handles uploading the corresponding file.
Handling the upload process for a file
The FileUpload
function accepts two inputs: an image element and a file from which to read the image data.
function FileUpload(img, file) { var reader = new FileReader(); this.ctrl = createThrobber(img); var xhr = new XMLHttpRequest(); this.xhr = xhr; var self = this; this.xhr.upload.addEventListener("progress", function(e) { if (e.lengthComputable) { var percentage = Math.round((e.loaded * 100) / e.total); self.ctrl.update(percentage); } }, false); xhr.upload.addEventListener("load", function(e){ self.ctrl.update(100); var canvas = self.ctrl.ctx.canvas; canvas.parentNode.removeChild(canvas); }, false); xhr.open("POST", "https://demos.hacks.mozilla.org/paul/demos/resources/webservices/devnull.php"); xhr.overrideMimeType('text/plain; charset=x-user-defined-binary'); reader.onload = function(evt) { xhr.send(evt.target.result); }; reader.readAsBinaryString(file); }
The FileUpload()
function shown above creates a throbber, which is used to display progress information, and then creates an XMLHttpRequest
to handle uploading the data.
Before actually transferring the data, several preparatory steps are taken:
- The
XMLHttpRequest
's uploadprogress
listener is set to update the throbber with new percentage information so that as the upload progresses the throbber will be updated based on the latest information. - The
XMLHttpRequest
's uploadload
event handler is set to update the throbber progress information to 100% to ensure the progress indicator actually reaches 100% (in case of granularity quirks during the process). It then removes the throbber since it's no longer needed. This causes the throbber to disappear once the upload is complete. - The request to upload the image file is opened by calling
XMLHttpRequest
'sopen()
method to start generating a POST request. - The MIME type for the upload is set by calling the
XMLHttpRequest
functionoverrideMimeType()
. In this case, we're using a generic MIME type; you may or may not need to set the MIME type at all depending on your use case. - The
FileReader
object is used to convert the file to a binary string. - Finally, when the content is loaded the
XMLHttpRequest
functionsend()
is called to upload the file's content.
sendAsBinary
method which was previously used in the example above is considered deprecated as of Gecko 31 (Firefox 31 / Thunderbird 31 / SeaMonkey 2.28); use the standard send(Blob data)
method instead.Handling the upload process for a file, asynchronously
<?php if (isset($_FILES['myFile'])) { // Example: move_uploaded_file($_FILES['myFile']['tmp_name'], "uploads/" . $_FILES['myFile']['name']); exit; } ?><!DOCTYPE html> <html> <head> <title>dnd binary upload</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <script type="text/javascript"> function sendFile(file) { var uri = "/index.php"; var xhr = new XMLHttpRequest(); var fd = new FormData(); xhr.open("POST", uri, true); xhr.onreadystatechange = function() { if (xhr.readyState == 4 && xhr.status == 200) { alert(xhr.responseText); // handle response. } }; fd.append('myFile', file); // Initiate a multipart/form-data upload xhr.send(fd); } window.onload = function() { var dropzone = document.getElementById("dropzone"); dropzone.ondragover = dropzone.ondragenter = function(event) { event.stopPropagation(); event.preventDefault(); } dropzone.ondrop = function(event) { event.stopPropagation(); event.preventDefault(); var filesArray = event.dataTransfer.files; for (var i=0; i<filesArray.length; i++) { sendFile(filesArray[i]); } } } </script> </head> <body> <div> <div id="dropzone" style="margin:30px; width:500px; height:300px; border:1px dotted grey;">Drag & drop your file here...</div> </div> </body> </html>
Example: Using object URLs to display PDF
Object URLs can be used for other things than just images! They can be used to display embedded PDF files or any other resources that can be displayed by the browser.
In Firefox, to have the PDF appear embedded in the iframe (rather than proposed as a downloaded file), the preference pdfjs.disabled
must be set to false
.
<iframe id="viewer">
And here is the change of the src
attribute:
var obj_url = window.URL.createObjectURL(blob); var iframe = document.getElementById('viewer'); iframe.setAttribute('src', obj_url); window.URL.revokeObjectURL(obj_url);
Example: Using object URLs with other file types
You can manipulate files of other formats the same way. Here is how to preview uploaded video:
var video = document.getElementById('video'); var obj_url = window.URL.createObjectURL(blob); video.src = obj_url; video.play() window.URL.revokeObjectURL(obj_url);
Specifications
- File upload state (HTML 5 working draft)
- File API
See also
File
FileList
FileReader
- Using XMLHttpRequest
- Using the DOM File API in chrome code
XMLHttpRequest
- jQuery JavaScript library