You are viewing documentation for Vaadin Framework 8 and related products View documentation for Vaadin Framework 7 ›
Basic Usage · Vaadin
Vaadin Elements - Upload - Basic Usage

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.

<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 dataTransfer.files, and here is when we do the validation and show the notice.

The properties that the user can configure for validation are:

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.

maxFileSize

The maximum allowed file size in bytes.

accept

A filter for the types of files the user can upload. A filter is a comma-separated list of allowed 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 HTML-4.01 file upload specification using MIME types patterns is widely supported, only certain browsers allow the file extension syntax introduced in the 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:

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

Events

The 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 preventDefault().

Event Details

All the events contain the File object in the event.detail.file property. The object has a number of extra properties to track the upload process:

file.uploadTarget

The target URL used to upload this file.

file.elapsed

Elapsed time since the upload started.

file.elapsedStr

Human-readable elapsed time.

file.remaining

Number of seconds remaining for the upload to finish.

file.remainingStr

Human-readable remaining time for the upload to finish.

file.speed

Upload speed in kB/s.

file.size

File size in bytes.

file.totalStr

Human-readable total size of the file.

file.loaded

Bytes transferred so far.

file.loadedStr

Human-readable uploaded size at the moment.

file.status

Status of the upload process.

file.error

Error message in case the upload failed.

file.progress

Percentage of the file already uploaded.

file.complete

True when the file was transferred to the server.

file.uploading

True while transferring data to the server.

Additionally, upload events also have an event.detail.xhr property with the corresponding XMLHttpRequest instance.

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

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:

<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.