Modular Upload
- Basic Usage
- Owner Component Lifecycle
- Using a Drop Zone
- Thumbnails
- Configuration
- Disabling Uploads
- Internationalization
- Related Components
|
Note
|
Preview Feature
This is a preview version of Modular Upload. You need to enable it with the feature flag |
The standard Upload component bundles a button, drop zone, file list, and upload management into a single component. UploadManager decouples these concerns into independent, composable pieces. Use it when you need to customize the upload layout, place the file list in a different location, omit UI components you don’t need, or integrate upload functionality into a custom component such as a chat input, form field, or toolbar.
UploadManager-
Non-visual. Handles file validation, upload queue management, and server communication. The three UI components below connect to it.
UploadButton-
A button that opens the file picker dialog. Automatically disables when the maximum file count is reached.
UploadDropZone-
A drag-and-drop target area that can wrap other content.
UploadFileList-
Displays files with progress indicators, status messages, and action buttons (retry, abort, remove).
Each component can be placed anywhere in your layout, independently of one another. Multiple components of the same type can also connect to a single manager — for example, two separate upload buttons in different parts of the UI. They all link to the same UploadManager instance, which coordinates their behavior.
Basic Usage
Create an UploadManager instance and pass it to the UI components. The components automatically synchronize with the manager’s state.
The UploadManager is created with an upload handler that processes the files. The UploadButton and UploadFileList components are linked to the manager and can be placed anywhere in the layout.
Owner Component Lifecycle
The UploadManager requires an owner component, typically the view or layout containing the upload UI. The manager’s lifecycle is tied to the owner’s lifecycle:
-
When the owner is detached from the UI or disabled, uploads stop working
-
Events fired by the manager use the owner as their source component
Source code
Java
// The view itself is typically used as the owner
public class MyView extends VerticalLayout {
public MyView() {
var manager = new UploadManager(this, handler);
// ...
}
}This design ensures that the upload infrastructure is automatically cleaned up when the view is removed, preventing resource leaks.
Using a Drop Zone
The UploadDropZone component provides drag-and-drop functionality. It can wrap other content, allowing users to drop files onto a larger area.
Source code
UploadManagerDropZone.java
upload-manager-drop-zone.tsx
upload-manager-drop-zone.ts
The drop zone applies a dragover attribute when files are dragged over it, which can be styled using CSS.
Thumbnails
The UploadFileList supports a thumbnails theme variant that displays uploaded files as a compact grid instead of a vertical list. Image files are shown with a thumbnail preview, while other file types display a file icon.
Source code
UploadManagerThumbnails.java
upload-manager-thumbnails.tsx
upload-manager-thumbnails.ts
Configuration
The UploadManager accepts an upload handler for processing files, and shares most of its configuration API with the standard Upload component — including upload restrictions (file count, size, and format), auto-upload, and event listeners.
The following sections describe where UploadManager differs from Upload.
File Type Restrictions
Unlike Upload, which uses a single setAcceptedFileTypes() method for both MIME types and extensions as a client-side hint, UploadManager provides two separate methods:
Source code
Java
// Accept by MIME type (wildcards supported)
manager.setAcceptedMimeTypes("image/*", "application/pdf");
// Accept by file extension (must start with a dot)
manager.setAcceptedFileExtensions(".pdf", ".docx", ".xlsx");When both are configured, a file must match at least one MIME type and at least one file extension. These restrictions are enforced both on the client side (to filter the file picker) and on the server side (to reject non-matching uploads). This is an improvement over Upload, which only validates file types on the client.
Event Differences
The FileRejectedEvent in UploadManager carries a typed FileRejectionReason enum (TOO_MANY_FILES, FILE_TOO_LARGE, INCORRECT_FILE_TYPE) instead of a raw error string, making it easier to handle specific rejection causes programmatically.
Upload progress events aren’t available as component event listeners. Use TransferProgressListener on the upload handler instead.
Disabling Uploads
|
Warning
|
Disabling UI components ( |
Use setEnabled() on the manager to securely control whether uploads are allowed. Disabling the manager prevents the server from accepting upload requests, regardless of the state of UI components. You can also disable individual UI components for visual feedback, but this should always be combined with disabling the manager for security.
Internationalization
The UploadFileList component supports internationalization (i18n) for its labels and messages:
Source code
Java
var i18n = new UploadFileListI18N()
.setFile(new UploadFileListI18N.File()
.setRetry("Try again")
.setStart("Upload")
.setRemove("Delete"))
.setError(new UploadFileListI18N.Error()
.setTooManyFiles("Too many files")
.setFileIsTooBig("File is too large")
.setIncorrectFileType("Invalid file type"));
fileList.setI18n(i18n);