Upload
- Usage
- Flow Usage
- Handling Uploaded Files (Java Only)
- Handling Upload Requests (Web Component Only)
- Drag and Drop
- Auto-Upload
- Upload Restrictions
- File Actions
- Internationalization (i18n)
- Customization
- Technical
- Best Practices
- Related Components
Upload is a component for uploading one or more files. It shows the upload progression and status of each file. Files can be uploaded using the Upload button or by dragging them onto the component.
Handling Uploaded Files (Java Only)
The Java Flow Upload component provides an API to handle uploaded file data directly, without having to set up an endpoint or a servlet.
It uses a Receiver
implementation to write the incoming file data into an OutputStream
.
The following default implementations of Receiver
are available:
| Handles a single file upload at once, writes the file data into an in-memory buffer.
Using |
| Handles multiple file uploads at once, writes the file data into a set of in-memory buffers. |
| Handles a single file upload at once, saves a file on the system.
Files are saved into the current working directory of the Java application.
Using |
| Handles multiple file uploads at once, and for each, saves a file on the system. Files are saved into the current working directory of the Java application. |
Source code
UploadMemoryBuffer.java
UploadFileBuffer.java
For more advanced use cases, you can provide custom implementations for Receiver
or MultiFileReceiver
, for example to save files into a specific directory, or uploading them to cloud storage.
Handling Upload Requests (Web Component Only)
Note
|
Web component only
This section is only relevant when using the Upload web component standalone. The Java/Flow component has its own set of APIs to handle file data directly, and doesn’t require the request to be handled manually. |
When using the Upload web component standalone, you need to set up an upload file handler or endpoint in your backend to handle the file upload request.
By default, the Upload component sends a request with the method type POST
, the content type multipart/form-data
, and the request URL is the current browser location.
Use the target
attribute to specify a different URL that should handle the upload request.
It’s also possible to customize other aspects of the request, such as the method or request headers.
Source code
HTML
<vaadin-upload
method="PUT"
target="/api/upload-handler"
headers='{ "X-API-KEY": "7f4306cb-bb25-4064-9475-1254c4eff6e5" }'>
</vaadin-upload>
Drag and Drop
Upload allows the user to drag files onto the component to upload them. Multiple files can be dropped simultaneously. By default, this is enabled on desktop and disabled on touch devices. Explicitly setting it to enabled or disabled affects both desktop and mobile devices.
Auto-Upload
By default, files are uploaded immediately they are added to the queue. Auto-upload can be disabled, for example to allow the user to review the list of files before initiating their upload by clicking the ▶️ button for each file. It’s recommended to change the button label to communicate that uploads don’t start automatically.
new tab
Source code
upload-auto-upload-disabled.ts
UploadAutoUploadDisabled.java
UploadExamplesI18N.java
UploadExamplesI18N.java
Uploads can be initiated programmatically when auto-upload is disabled, for example if you want to provide the user with a single button to start all uploads.
new tab
Source code
upload-all-files.ts
UploadAllFiles.java
UploadExamplesI18N.java
UploadExamplesI18N.java
Upload Restrictions
You can set three types of restrictions: file format, file count, and file size.
Exceptions that arise from the user violating any of the imposed restrictions aren’t shown in the UI by default. Use a File Rejected listener to catch these exceptions and, for example, a Notification to inform the user of the problem, together with any potential solutions.
However, the user should be informed upfront about any file upload restrictions. Limitations on the maximum number of files allowed, file size, and format should all be communicated clearly, to avoid exceptions as much as possible.
File Format
Upload can be configured to accept only files of specific formats.
The acceptable file formats are set using MIME type patterns or file extensions, for example "video/*"
, "image/tiff"
or ".pdf"
and "audio/mp3"
.
new tab
Source code
upload-file-format.ts
UploadFileFormat.java
UploadExamplesI18N.java
UploadExamplesI18N.java
Note
|
Prefer MIME Type
Although MIME types are widely supported, file extensions are only implemented in certain browsers and should be avoided.
|
File Count
By default, Upload doesn’t limit the number of files that can be uploaded. If you set the maximum to one, the native file browser prevents multiple files from being selected.
Note
|
Java Flow-specific
When using a |
new tab
Source code
upload-file-count.ts
UploadFileCount.java
UploadExamplesI18N.java
UploadExamplesI18N.java
File Size
Upload allows you to limit the file size by setting a maximum, in bytes. By default, there is no limit.
new tab
Source code
upload-file-size.ts
UploadFileSize.java
UploadExamplesI18N.java
UploadExamplesI18N.java
Note
|
Revalidate the size limit in the server
This constraint is set on the client and is checked before contacting the server. |
File Actions
Each file has a certain set of associated actions available, depending on its upload state. A file always has a Clear/Remove button. This button cancels the upload (if applicable) and removes the file from the list.
The Clear/Remove button is the only available action during and after a successful upload.
new tab
Source code
upload-clear-button.ts
upload-clear-button.ts
Note
|
Remember to remove the file from the backend
The Clear/Remove button doesn’t remove a successfully uploaded file from the server file system or database. It’s only removed from the file list. |
If an error or exception occurs, Upload displays a Retry button that tries to upload the file again when pressed.
new tab
Source code
upload-retry-button.ts
upload-retry-button.ts
When a file is queued (auto-upload disabled) it has a Start Button that the user must press to begin the upload process.
new tab
Source code
upload-start-button.ts
upload-start-button.ts
Internationalization (i18n)
All the labels and messages in Upload are configurable. For a complete list, see the API documentation (Java, Web component).
new tab
Source code
upload-internationalization.ts
UploadInternationalization.java
UploadFinnishI18N.java
UploadFinnishI18N.java
Customization
You can replace the default upload button. For example, if Upload needs a stronger emphasis, you can use a primary button.
new tab
Source code
upload-button-theme-variant.ts
UploadButtonThemeVariant.java
UploadExamplesI18N.java
UploadExamplesI18N.java
You can also customize the drop label, as well as the icon.
Note
|
Use a large drop target
When customizing the Upload component, make sure not to make the drop target too small. A large drop target is easier to use and less error-prone. |
Technical
Listeners
Upload has listeners for the following events:
Event | Description |
---|---|
All Finished | Triggered when Upload has processed all the files in its queue, regardless of whether all the uploads were successful |
Failed | When the upload is received but the reception is interrupted for some reason |
File Rejected | Sent when the file selected for upload doesn’t meet the constraints, for example file size |
Finished | Sent when Upload receives a file, regardless of whether the upload was successful (to distinguish between the two cases, use either Succeeded or Failed listeners) |
Progress | Event for tracking upload progress |
Started | Triggered when the upload starts |
Succeeded | Sent when the upload has been successfully received |
Best Practices
Labeling
Choose labels that are informative and instructional. For example, if the user is to upload a single PDF file, it’s better to have the button label say "Upload PDF…" instead of "Upload File…". The task becomes clearer and improves accessibility for the user, especially if they are using a screen reader, as the button’s label is read aloud when focused.
new tab
Source code
upload-labelling.ts
UploadLabelling.java
UploadExamplesI18N.java
UploadExamplesI18N.java
Likewise, if the user is expected to upload a spreadsheet but multiple file formats are accepted, have the button say "Upload Spreadsheet", with helpers to inform the user which formats are accepted.
new tab
Source code
upload-helper.ts
UploadHelper.java
UploadExamplesI18N.java
UploadExamplesI18N.java
Error Messages
Try to provide meaningful feedback and error messages when an exception or error occurs. Avoid technical jargon and instead try to provide solutions/instructions on how to fix the error.
A "Server Unavailable" might suffice for tech-savvy users but, for some, it might not be helpful at all. Your error messages should be written with your users in mind.
new tab