fileUploadField

fileUploadField uploads a file into memory as a byte array.

XML Element

fileUploadField

Java Class

FileUploadField

Basics

The component can contain a label, a link to the uploaded file, and an upload button. When the upload button is clicked, a standard file picker dialog pops up, allowing the user to select a file.

fileUploadField can work both without being bound to an entity attribute and with data binding.

Below we will show an example of using the component without data binding. You can use it to handle the uploaded file directly without associating it with any Jmix entity. This is great for situations where you want to process the file, save it to a different location, or perform some other operation without storing it persistently in the database.

<fileUploadField id="fileUploadField"
                 clearButtonVisible="true"
                 fileNameVisible="true"
                 dropAllowed="true"
                 acceptedFileTypes=".pdf, .jpeg, .jpg, .png, .doc, .docx"
                 maxFileSize="921600"
                 label="msg://fileUploadField.label"
                 helperText="msg://fileUploadField.helperText"
                 fileTooBigText="msg://fileUploadField.fileTooBigText"/>

Now you can handle the uploaded file directly within the FileUploadSucceededEvent:

@Autowired
private Notifications notifications;

@Subscribe("fileUploadField")
public void onFileUploadFieldFileUploadSucceeded(final FileUploadSucceededEvent<FileStorageUploadField, byte[]> event) {
    notifications.create("Your file %s has been uploaded successfully.".formatted(event.getFileName()))
            .withThemeVariant(NotificationVariant.LUMO_PRIMARY)
            .show();
}
Internally, fileUploadField uses Vaadin’s UploadHandler API and stores the uploaded file in memory as a byte array. No physical file is created on the file system, so this approach is best suited for smaller files that don’t require persistent storage.

For uploading and saving large files it is recommended to use the fileStorageUploadField component.

To upload multiple files simultaneously, you should use the upload component instead of fileUploadField.

Data-aware fileUploadField

LIVE DEMO

fileUploadField allows users to save the uploaded file to an entity attribute as a byte array.

In the example below, the document attribute of the User entity has the byte array type.

@Column(name = "DOCUMENT")
private byte[] document;
<data>
    <instance id="pictureDc" class="io.jmix.uisamples.entity.Picture">
    </instance>
</data>
<layout>
    <fileUploadField id="fileUploadField" label="Select File"
                     dataContainer="pictureDc" property="content"
                     clearButtonVisible="true"
                     fileNameVisible="true"
                     dropAllowed="true"
                     maxFileSize="51200"
                     acceptedFileTypes="image/png,image/jpeg"
    />
</layout>

fileUploadField has a link to the container specified in the dataContainer attribute; the property attribute contains the name of the entity attribute that is displayed in fileUploadField.

To store the file in the file storage and link to the entity as FileRef, use the fileStorageUploadField component.

Attributes

The following attributes are specific to fileUploadField:

Name Description Default

acceptedFileTypes

Sets the accepted file types.

—

clearButtonAriaLabel

Sets the clear button aria label.

—

clearButtonVisible

Controls whether the field displays a clear button.

false

connectingStatusText

Sets the connecting status text.

—

dropAllowed

Controls whether users can drag files onto the upload area.

—

fileName

Sets the text that should be shown if the value is set from the data container.

—

fileNameVisible

Controls whether the selected file name is displayed.

—

fileNotSelectedText

Sets the file not selected text.

—

fileTooBigText

Sets the file too big text.

—

incorrectFileTypeText

Sets the incorrect file type text.

—

maxFileSize

Sets the maximum file size.

—

processingStatusText

Sets the processing status text.

—

remainingTimeText

Sets the remaining time text.

—

remainingTimeUnknownText

Sets the remaining time unknown text.

—

uploadDialogCancelText

Sets the upload dialog cancel text.

—

uploadDialogTitle

Sets the upload dialog title.

—

uploadIcon

Sets the upload icon.

—

uploadText

Sets the upload text.

—

The following shared attributes are supported by fileUploadField:

id - alignSelf - classNames - colspan - css - dataContainer - enabled - errorMessage - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - visible - width

Handlers

The following handlers are specific to fileUploadField:

Name Description

FileUploadFailedEvent

Fired when uploading a file fails.

FileUploadFileRejectedEvent

Fired when a selected file is rejected because it violates an upload constraint.

FileUploadFinishedEvent

Fired after an upload finishes.

FileUploadProgressEvent

Fired as upload progress changes.

FileUploadStartedEvent

Fired when uploading a file starts.

FileUploadSucceededEvent

io.jmix.flowui.kit.component.upload.event.FileUploadSucceededEvent is fired when the Upload component fires SucceededEvent.

validator

Validates the component value.

The following shared handlers are supported by fileUploadField:

AttachEvent - ComponentValueChangeEvent - DetachEvent - statusChangeHandler

Elements

A fileUploadField can include tooltip and uploadIcon as its nested elements.