upload

LIVE DEMO

upload allows users to upload one or multiple files. It displays the upload progress and the status of each file. Files can be uploaded by clicking the Upload files button or by dragging them onto the component.

XML Element

upload

Java Class

JmixUpload

Attributes

id - acceptedFileTypes - alignSelf - autoUpload - classNames - colspan - css - dropAllowed - dropLabel - dropLabelIcon - enabled - height - maxFileSize - maxFiles - maxHeight - maxWidth - minHeight - minWidth - uploadHandlerFqn - uploadHandlerType - uploadIcon - uploadText - visible - width

Handlers

AllFinishedEvent - AttachEvent - DetachEvent - FailedEvent - FileRejectedEvent - FileRemovedEvent - FinishedEvent - ProgressUpdateEvent - StartedEvent - UploadSucceededEvent

Elements

uploadIcon - dropLabelIcon

Basics

An example of upload:

<upload id="upload"
        maxFiles="2"
        autoUpload="false"/>
upload basics

Auto-Upload

The autoUpload attribute determines whether files should be uploaded automatically as soon as they are selected, or if the user needs to explicitly trigger the upload.

  • When true, files are uploaded immediately after selection. The upload progress bar is displayed, and the user can cancel the upload if needed.

  • When false, files are not uploaded automatically. The user must click the Upload button to start the upload process.

The default value is true.

Drag & Drop

The upload component supports drag and drop functionality, allowing users to upload files by simply dragging them from their file system and dropping them onto the component.

Drag & drop functionality is enabled by default. To disable it, set the dropAllowed attribute to false.

The dropLabel attribute allows you to customize the message that prompts users to drop files into the upload area.

The attribute value can either be the text itself or a key in the message bundle. In case of a key, the value should begin with the msg:// prefix.

The dropLabelIcon attribute allows you to specify an icon to be displayed along with the dropLabel text.

<upload dropLabel="Drop files here to upload"
        dropLabelIcon="vaadin:cloud-upload-o"/>
upload drag drop

File Count

By default, upload doesn’t have a limit on the number of files that can be uploaded. You can set a file count limit using the maxFiles attribute.

This attribute specifies the maximum number of files to upload. If the value is set to one, the native file browser will prevent selecting multiple files.

Exceptions that arise aren’t shown in the UI by default. Use FileRejectedEvent to catch those exceptions and, for example, a notification to inform the user of the problem.

@Autowired
private Notifications notifications;

@Subscribe("upload")
public void onUploadFileRejected(final FileRejectedEvent event) {
    notifications.create(event.getErrorMessage())
            .show();
}

Attributes

Common attributes serve the same purpose for all components.

The following attributes are specific to upload:

Name

Description

Default

autoUpload

Sets whether the component allows uploads to start immediately after selecting files. See Auto-Upload.

true

dropLabel

Specifies the drop label to show as a message to the user to drop files in the upload component. See Drag & Drop.

dropLabelIcon

Sets the icon for the drop label. The icon is visible when the user can drop files to this upload component. See Drag & Drop.

maxFiles

Specifies the maximum number of files to upload. See File Count.

unlimited

uploadHandlerFqn

Sets the fully qualified name of a custom upload handler implementation for this upload component. The class must implement Vaadin’s UploadHandler interface. Example value:

  • com.company.app.upload.CustomUploadHandler

uploadHandlerType

Specifies the type of the built-in upload handler. Possible values are:

  • IN_MEMORY – Stores uploaded data in memory using InMemoryUploadHandler. In UploadSucceededEvent<V>, the uploaded data is available as byte[].

  • FILE_TEMPORARY_STORAGE Stores uploaded files in the temporary storage.

IN_MEMORY

Handlers

Common handlers are configured in the same way for all components.

The following handlers are specific to upload.

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

Name

Description

AllFinishedEvent

com.vaadin.flow.component.upload.AllFinishedEvent is sent when upload has processed all the files in its upload queue, regardless of whether all the receptions were successful or not.

FailedEvent

com.vaadin.flow.component.upload.FailedEvent is sent when upload is received, but the reception is interrupted for some reason. Use addUploadFailedListener() in Java code.

FileRejectedEvent

com.vaadin.flow.component.upload.FileRejectedEvent is sent when the selected file doesn’t meet the constraints specified on upload, for example, file size limit or file count limit. See File Count.

FileRemovedEvent

com.vaadin.flow.component.upload.FileRemovedEvent is sent when a file is removed from the upload queue.

FinishedEvent

com.vaadin.flow.component.upload.FinishedEvent is sent when upload receives a file, regardless of whether the reception was successful or failed. Use addUploadFinishedListener() in Java code.

ProgressUpdateEvent

com.vaadin.flow.component.upload.ProgressUpdateEvent is sent to track progress of upload. Use addUploadProgressListener() in Java code.

StartedEvent

com.vaadin.flow.component.upload.StartedEvent is sent when upload is started to receive. Use addUploadStartedListener() in Java code or subscribe to the component event in a view controller.

UploadSucceededEvent

io.jmix.flowui.component.upload.UploadSucceededEvent<V> is sent when upload is received successfully. The event provides uploaded data through getData(). In a Jmix view controller, subscribe to this event with @Subscribe("upload"). You can also use addUploadSucceededListener() in Java code.

@Autowired
private Notifications notifications;

@Subscribe("upload")
public void onUploadUploadSucceeded(final UploadSucceededEvent<?> event) {
    notifications.create(
                    "Your file %s has been uploaded successfully.".formatted(
                            event.getFileName()))
            .withThemeVariant(NotificationVariant.LUMO_PRIMARY)
            .show();
}

See Also

See Vaadin Docs for more information.