---
title: Basic Usage
order: 2
layout: page
---


[[vaadin-upload.basic]]
= Basic Usage

The user can select files to upload by using the file selector in the browser or by dropping the files from the desktop into the component.

[source,html]
----
<vaadin-upload target="http://foo.bar/upload"></vaadin-upload>
----

== Validations

You can restrict the type and size of files, and the maximum number of files to upload, by using either element attributes or the JavaScript API.

The validation is done just before the request is sent to the server. It fails if any of the conditions don't match, in which case a notice is shown to the user.

While dragging is being done, we cannot read the types, names, and sizes of the files due to security reasons.
Only when the file is dropped into the component, we can access the [propertyname]#dataTransfer.files#, and here is when we do the validation and show the notice.

The properties that the user can configure for validation are:

[propertyname]#maxFiles#:: Meaning the max number of files that the user can select to upload. When the list is full, the user may add new files after removing some files from the list.
[propertyname]#maxFileSize#:: The maximum allowed file size in bytes.
[propertyname]#accept#:: A filter for the types of files the user can upload. A filter is a comma-separated list of allowed http://www.sitepoint.com/web-foundations/mime-types-complete-list/[MIME types] or file extensions.
Browsers use this information to filter out non-conforming files when prompting the user to select files.
Notice that although the https://www.w3.org/TR/html401/interact/forms.html#adef-accept[HTML-4.01 file upload] specification using MIME types patterns is widely supported,
only certain browsers allow the file extension syntax introduced in the https://www.w3.org/TR/html5/forms.html#file-upload-state-%28type=file%29[HTML5] specification.

Nevertheless, this component will always validate file types and extensions before sending any file to the server, despite differences in browser syntax support.

You can use validation parameters as follows:

[source,html]
----
<vaadin-upload max-files="3" max-file-size="1000000"
               accept="application/pdf,image/*">
</vaadin-upload>
----

== Events

The [vaadinelement]#vaadin-upload# element dispatches events when files are added, removed, or rejected, and for every upload state change for each file.
You can use the events to change the behaviour of the upload process. Such customizations may require preventing the default actions, which you can do with [methodname]#preventDefault()#.

=== Event Details
All the events contain the [classname]#File# object in the [propertyname]#event.detail.file# property.
The object has a number of extra properties to track the upload process:

[propertyname]#file.uploadTarget#:: The target URL used to upload this file.
[propertyname]#file.elapsed#:: Elapsed time since the upload started.
[propertyname]#file.elapsedStr#:: Human-readable elapsed time.
[propertyname]#file.remaining#:: Number of seconds remaining for the upload to finish.
[propertyname]#file.remainingStr#:: Human-readable remaining time for the upload to finish.
[propertyname]#file.speed#:: Upload speed in kB/s.
[propertyname]#file.size#:: File size in bytes.
[propertyname]#file.totalStr#:: Human-readable total size of the file.
[propertyname]#file.loaded#:: Bytes transferred so far.
[propertyname]#file.loadedStr#:: Human-readable uploaded size at the moment.
[propertyname]#file.status#:: Status of the upload process.
[propertyname]#file.error#:: Error message in case the upload failed.
[propertyname]#file.progress#:: Percentage of the file already uploaded.
[propertyname]#file.complete#:: True when the file was transferred to the server.
[propertyname]#file.uploading#:: True while transferring data to the server.

Additionally, upload events also have an [propertyname]#event.detail.xhr# property with the corresponding [classname]#XMLHttpRequest# instance.

In the following example, we listen to `upload-start` events, which are fired when the file upload process starts.

[source,javascript]
----
var upload = document.querySelector('vaadin-upload');
upload.addEventListener('upload-start', function(e) {
  alert("Uploading " + event.detail.file.name);
});
----

When using the element inside another Polymer element, you can use the declarative binding syntax to subscribe for an event:

[source,html]
----
<dom-module id="my-element">
  <template>
    <vaadin-upload on-upload-start="uploadStarted"></vaadin-upload>
  </template>
</dom-module>
<script>
  Polymer({
    is: 'my-element',
    uploadStarted: function(event) {
      alert("Uploading " + event.detail.file.name);
    }
  });
</script>
----

=== Event List

The following events are fired by the component in different phases of the upload process:

`file-reject`:: Fired when a file cannot be added to the queue due to a validation constraint.
`upload-abort`:: Fired when file abort is requested. If the default is prevented, the file upload will not be aborted.
`upload-before`:: Fired before the XHR is opened. It is useful for changing the request URL based on the file name, etc.
`upload-error`:: Fired if the upload process failed.
`upload-progress`:: Fired as many times as a file progress is updated.
`upload-request`:: Fired when the request has been opened but not yet sent. It is useful for appending additional data keys to the request and for changing some parameters such as headers.
  If the event is default-prevented, then the request is not sent to the server. In this case, you can send the XHR manually.
`upload-response`:: Fired when the server response was received, but before the component processes it. It is useful for making the upload fail depending on the response.
  If the event is default-prevented, the vaadin-upload skips the default flow, allowing the developer to do something on his own, such as retrying the upload.
`upload-retry`:: Fired when the upload is retried. If the default is prevented, retry would not be performed.
`upload-start`:: Fired when the XHR is sent.
`upload-success`:: Fired if the upload process succeeds.