Upload

Handling Uploaded Files
Drag & 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 via drag and drop.

Open in a
new tab

Source code

UploadBasic.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

import java.io.InputStream;

@Route("upload-basic")
public class UploadBasic extends Div {

    public UploadBasic() {
        // tag::snippet[]
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        Upload upload = new Upload(buffer);

        upload.addSucceededListener(event -> {
            String fileName = event.getFileName();
            InputStream inputStream = buffer.getInputStream(fileName);

            // Do something with the file data
            // processFile(inputStream, fileName);
        });
        // end::snippet[]


        add(upload);
    }

}

Handling Uploaded Files

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:

MemoryBuffer

Handles a single file upload at once, writes the file data into an in-memory buffer. Using MemoryBuffer automatically configures the component so that only a single file can be selected.

MultiFileMemoryBuffer

Handles multiple file uploads at once, writes the file data into a set of in-memory buffers.

FileBuffer

Handles a single file upload at once, saves a file on the system. Files are going to be saved into the current working directory of the Java application. Using FileBuffer automatically configures the component so that only a single file can be selected.

MultiFileMemoryBuffer

Handles multiple file uploads at once, and for each, saves a file on the system. Files are going to be saved into the current working directory of the Java application.

Source code

UploadMemoryBuffer.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;

import java.io.InputStream;

public class UploadMemoryBuffer extends Div {
    public UploadMemoryBuffer() {
        /* Example for MemoryBuffer */
        MemoryBuffer memoryBuffer = new MemoryBuffer();
        Upload singleFileUpload = new Upload(memoryBuffer);

        singleFileUpload.addSucceededListener(event -> {
            // Get information about the uploaded file
            InputStream fileData = memoryBuffer.getInputStream();
            String fileName = event.getFileName();
            long contentLength = event.getContentLength();
            String mimeType = event.getMIMEType();

            // Do something with the file data
            // processFile(fileData, fileName, contentLength, mimeType);
        });

        /* Example for MultiFileMemoryBuffer */
        MultiFileMemoryBuffer multiFileMemoryBuffer = new MultiFileMemoryBuffer();
        Upload multiFileUpload = new Upload(multiFileMemoryBuffer);

        multiFileUpload.addSucceededListener(event -> {
            // Determine which file was uploaded
            String fileName = event.getFileName();

            // Get input stream specifically for the finished file
            InputStream fileData = multiFileMemoryBuffer.getInputStream(fileName);
            long contentLength = event.getContentLength();
            String mimeType = event.getMIMEType();

            // Do something with the file data
            // processFile(fileData, fileName, contentLength, mimeType);
        });

        add(singleFileUpload, multiFileUpload);
    }
}
UploadFileBuffer.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.FileBuffer;
import com.vaadin.flow.component.upload.receivers.FileData;
import com.vaadin.flow.component.upload.receivers.MultiFileBuffer;

public class UploadFileBuffer extends Div {
    public UploadFileBuffer() {
        /* Example for FileBuffer */
        FileBuffer fileBuffer = new FileBuffer();
        Upload singleFileUpload = new Upload(fileBuffer);

        singleFileUpload.addSucceededListener(event -> {
            // Get information about the file that was written to the file system
            FileData savedFileData = fileBuffer.getFileData();
            String absolutePath = savedFileData.getFile().getAbsolutePath();

            System.out.printf("File saved to: %s%n", absolutePath);
        });

        /* Example for MultiFileBuffer */
        MultiFileBuffer multiFileBuffer = new MultiFileBuffer();
        Upload multiFileUpload = new Upload(multiFileBuffer);

        multiFileUpload.addSucceededListener(event -> {
            // Determine which file was uploaded successfully
            String uploadFileName = event.getFileName();
            // Get information for that specific file
            FileData savedFileData = multiFileBuffer.getFileData(uploadFileName);
            String absolutePath = savedFileData.getFile().getAbsolutePath();

            System.out.printf("File saved to: %s%n", absolutePath);
        });

        add(singleFileUpload, multiFileUpload);
    }
}

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 a Cloud storage.

Drag & Drop

Upload supports drag and drop for uploading files. Multiple files can be dropped simultaneously. By default, it’s enabled on desktop and disabled on touch devices. By explicitly setting it to enabled or disabled affects both desktop and mobile devices.

Open in a
new tab

Source code

UploadDragAndDrop.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.formlayout.FormLayout;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Label;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-drag-and-drop")
public class UploadDragAndDrop extends Div {

    public UploadDragAndDrop() {
        MultiFileMemoryBuffer buffer1 = new MultiFileMemoryBuffer();
        MultiFileMemoryBuffer buffer2 = new MultiFileMemoryBuffer();

        // tag::snippet[]
        Upload dropEnabledUpload = new Upload(buffer1);
        dropEnabledUpload.setDropAllowed(true);

        Upload dropDisabledUpload = new Upload(buffer2);
        dropDisabledUpload.setDropAllowed(false);
        // end::snippet[]

        Label dropEnabledLabel = new Label("Drag and drop enabled");
        dropEnabledLabel.getStyle().set("font-weight", "600");
        dropEnabledUpload.setId("upload-drop-enabled");
        dropEnabledLabel.setFor(dropEnabledUpload.getId().get());

        Label dropDisabledLabel = new Label("Drag and drop disabled");
        dropDisabledLabel.getStyle().set("font-weight", "600");
        dropDisabledUpload.setId("upload-drop-disabled");
        dropDisabledLabel.setFor(dropDisabledUpload.getId().get());

        Div leftSection = new Div(dropEnabledLabel, dropEnabledUpload);
        Div rightSection = new Div(dropDisabledLabel, dropDisabledUpload);

        FormLayout formLayout = new FormLayout(leftSection, rightSection);
        formLayout.setResponsiveSteps(new FormLayout.ResponsiveStep("0", 1),
                new FormLayout.ResponsiveStep("520px", 2));

        add(formLayout);
    }

}

Auto Upload

By default, files are uploaded immediately as 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 is recommended to change the button label to indicate that uploads do not start automatically.

Open in a
new tab

Source code

UploadAutoUploadDisabled.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-auto-upload-disabled")
public class UploadAutoUploadDisabled extends Div {

    public UploadAutoUploadDisabled() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setAutoUpload(false);

        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getAddFiles()
                .setMany("Select Files...");
        upload.setI18n(i18n);
        // end::snippet[]


        add(upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
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.

Open in a
new tab

Source code

UploadAllFiles.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.button.ButtonVariant;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-all-files")
public class UploadAllFiles extends Div {

    public UploadAllFiles() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setAutoUpload(false);

        Button uploadAllButton = new Button("Upload All Files");
        uploadAllButton.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
        uploadAllButton.addClickListener(event -> {
            // No explicit Flow API for this at the moment
            upload.getElement().callJsFunction("uploadFiles");
        });

        // end::snippet[]
        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getAddFiles()
                .setMany("Select Files...");
        upload.setI18n(i18n);


        add(upload, uploadAllButton);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
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 about the problem at hand and any potential solutions.

However, the user should be informed upfront about any file upload restrictions. Maximum number of files allowed, file size and format limitations should all be communicated clearly to avoid exceptions whenever possible.

File Format

Upload can be configured to only accept 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".

Open in a
new tab

Source code

UploadFileFormat.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H4;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.notification.Notification;
import com.vaadin.flow.component.notification.NotificationVariant;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-file-format")
public class UploadFileFormat extends Div {

    public UploadFileFormat() {
        MemoryBuffer buffer = new MemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setAcceptedFileTypes("application/pdf", ".pdf");

        upload.addFileRejectedListener(event -> {
            String errorMessage = event.getErrorMessage();

            Notification notification = Notification.show(
                    errorMessage,
                    5000,
                    Notification.Position.MIDDLE
            );
            notification.addThemeVariants(NotificationVariant.LUMO_ERROR);
        });
        // end::snippet[]

        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getAddFiles().setOne("Upload Report...");
        i18n.getDropFiles().setOne("Drop report here");
        i18n.getError()
                .setIncorrectFileType(
                        "The provided file does not have the correct format. Please provide a PDF document.");
        upload.setI18n(i18n);

        H4 title = new H4("Upload report");
        title.getStyle().set("margin-top", "0");
        Paragraph hint = new Paragraph("Accepted file formats: PDF (.pdf)");
        hint.getStyle().set("color", "var(--lumo-secondary-text-color)");

        add(title, hint, upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
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

Upload does not limit the number of files that can be uploaded by default. If you set the maximum to one the native file browser prevents selecting multiple files.

Note

Receiver-specific Restrictions

When using a Receiver that does not implement the MultiFileReceiver interface, such as MemoryBuffer or FileBuffer, the Upload component will automatically limit the number of files to one. That is because these receiver implementations only support handling a single file at once.

Open in a
new tab

Source code

UploadFileCount.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H4;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.notification.Notification;
import com.vaadin.flow.component.notification.NotificationVariant;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-file-count")
public class UploadFileCount extends Div {

    public UploadFileCount() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setMaxFiles(3);

        upload.addFileRejectedListener(event -> {
            String errorMessage = event.getErrorMessage();

            Notification notification = Notification.show(
                    errorMessage,
                    5000,
                    Notification.Position.MIDDLE
            );
            notification.addThemeVariants(NotificationVariant.LUMO_ERROR);
        });
        // end::snippet[]

        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getError()
                .setTooManyFiles(
                        "You may only upload a maximum of three files at once.");
        upload.setI18n(i18n);

        H4 title = new H4("Upload files");
        title.getStyle().set("margin-top", "0");
        Paragraph hint = new Paragraph("Maximum of 3 files allowed");
        hint.getStyle().set("color", "var(--lumo-secondary-text-color)");

        add(title, hint, upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
UploadExamplesI18N.java

File Size

Upload allows you to limit the file size by setting a maximum. The limit is defined in bytes. It’s unlimited by default.

Open in a
new tab

Source code

UploadFileSize.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H4;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.notification.Notification;
import com.vaadin.flow.component.notification.NotificationVariant;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-file-size")
public class UploadFileSize extends Div {

    public UploadFileSize() {
        MemoryBuffer buffer = new MemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);

        int maxFileSizeInBytes = 10 * 1024 * 1024; // 10MB
        upload.setMaxFileSize(maxFileSizeInBytes);

        upload.addFileRejectedListener(event -> {
            String errorMessage = event.getErrorMessage();

            Notification notification = Notification.show(
                    errorMessage,
                    5000,
                    Notification.Position.MIDDLE
            );
            notification.addThemeVariants(NotificationVariant.LUMO_ERROR);
        });
        // end::snippet[]

        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getError()
                .setFileIsTooBig(
                        "The file exceeds the maximum allowed size of 10MB.");
        upload.setI18n(i18n);

        H4 title = new H4("Upload file");
        title.getStyle().set("margin-top", "0");
        Paragraph hint = new Paragraph("Maximum file size: 10 MB");
        hint.getStyle().set("color", "var(--lumo-secondary-text-color)");

        add(title, hint, upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
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.

Open in a
new tab

Source code

upload-clear-button.tsimport { html, LitElement, customElement } from 'lit-element';
import '@vaadin/vaadin-upload/vaadin-upload';
import { applyTheme } from 'Frontend/generated/theme';

function createFakeFiles() {
  return createFakeUploadFiles([
    {
      name: 'Workflow.pdf',
      progress: 60,
      status: '19.7 MB: 60% (remaining time: 00:12:34)',
    },
    { name: 'Financials.xlsx', complete: true },
  ]);
}

@customElement('upload-clear-button')
export class Example extends LitElement {
  protected createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  render() {
    return html`<vaadin-upload .files="${createFakeFiles()}"></vaadin-upload>`;
  }
}
upload-clear-button.ts

Note	Remember to remove the file from the back end The "Clear/Remove" button does not remove a successfully uploaded file from the server file system or database. It is only removed from Upload’s file list.

If an error or exception occurs Upload displays a "Retry" button that attempts to upload the file again when pressed.

Open in a
new tab

Source code

upload-retry-button.tsimport { html, LitElement, customElement } from 'lit-element';
import '@vaadin/vaadin-upload/vaadin-upload';
import { applyTheme } from 'Frontend/generated/theme';

function createFakeFiles() {
  return createFakeUploadFiles([
    { name: 'Financials.xlsx', error: 'Something went wrong, please try again' },
  ]);
}

@customElement('upload-retry-button')
export class Example extends LitElement {
  protected createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  render() {
    return html`<vaadin-upload .files="${createFakeFiles()}"></vaadin-upload>`;
  }
}
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.

Open in a
new tab

Source code

upload-start-button.tsimport { html, LitElement, customElement } from 'lit-element';
import '@vaadin/vaadin-upload/vaadin-upload';
import { applyTheme } from 'Frontend/generated/theme';

function createFakeFiles() {
  return createFakeUploadFiles([
    {
      name: 'Workflow.pdf',
      status: 'Queued',
      held: true,
    },
  ]);
}

@customElement('upload-start-button')
export class Example extends LitElement {
  protected createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  render() {
    return html`<vaadin-upload .files="${createFakeFiles()}"></vaadin-upload>`;
  }
}
upload-start-button.ts

Internationalization (i18n)

All of Upload’s labels and messages are configurable. For a complete list please refer to the API documentation (Java).

Open in a
new tab

Source code

UploadInternationalization.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-internationalization")
public class UploadInternationalization extends Div {

    public UploadInternationalization() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);

        // Please see the separate UploadFinnishI18N class / file
        // in this example for the I18N configuration
        UploadFinnishI18N i18N = new UploadFinnishI18N();
        upload.setI18n(i18N);
        // end::snippet[]

        add(upload);
    }

}
UploadFinnishI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 * Please make sure that you have set all translations when writing a custom
 * I18N config.
 */
public class UploadFinnishI18N extends UploadI18N {
    public UploadFinnishI18N() {
        setDropFiles(new DropFiles()
                .setOne("Raahaa tiedosto tähän")
                .setMany("Raahaa tiedostot tähän"));
        setAddFiles(new AddFiles()
                .setOne("Valitse tiedosto...")
                .setMany("Valitse tiedostot..."));
        setCancel("Peruuta");
        setError(new Error()
                .setTooManyFiles("Liian monta tiedostoa.")
                .setFileIsTooBig("Tiedosto on liian suuri.")
                .setIncorrectFileType("Väärä tiedostomuoto."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Yhdistetään...")
                        .setStalled("Pysäytetty")
                        .setProcessing("Käsitellään tiedostoa...")
                        .setHeld("Jonossa"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("aikaa jäljellä: ")
                        .setUnknown("jäljellä olevaa aikaa ei saatavilla"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Palvelin ei vastaa")
                        .setUnexpectedServerError("Palvelinvirhe")
                        .setForbidden("Kielletty")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
UploadFinnishI18N.java

Customization

You can replace the default upload button. For example, if Upload needs a stronger emphasis you can use a primary button.

Open in a
new tab

Source code

UploadButtonThemeVariant.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.button.ButtonVariant;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-button-theme-variant")
public class UploadButtonThemeVariant extends Div {

    public UploadButtonThemeVariant() {
        MemoryBuffer buffer = new MemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setAcceptedFileTypes("application/pdf", ".pdf");

        Button uploadButton = new Button("Upload PDF...");
        uploadButton.addThemeVariants(ButtonVariant.LUMO_PRIMARY);

        upload.setUploadButton(uploadButton);

        // Disable the upload button after the file is selected
        // Re-enable the upload button after the file is cleared
        upload.getElement().addEventListener("max-files-reached-changed", event -> {
            boolean maxFilesReached = event.getEventData().getBoolean("event.detail.value");
            uploadButton.setEnabled(!maxFilesReached);
        }).addEventData("event.detail.value");
        // end::snippet[]

        UploadExamplesI18N i18N = new UploadExamplesI18N();
        i18N.getDropFiles().setOne("Drop PDF here");
        upload.setI18n(i18N);

        add(upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
UploadExamplesI18N.java

You can also customize the drop label, as well as the icon.

Open in a
new tab

Source code

UploadDropLabel.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Anchor;
import com.vaadin.flow.component.html.AnchorTarget;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Span;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-drop-label")
public class UploadDropLabel extends Div {

    public UploadDropLabel() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);

        Span dropLabel = createDropLabel();
        Icon dropIcon = VaadinIcon.CLOUD_UPLOAD_O.create();

        upload.setDropLabel(dropLabel);
        upload.setDropLabelIcon(dropIcon);
        // end::snippet[]

        add(upload);
    }

    private static Span createDropLabel() {
        Span cloudHint = new Span(
                "Files will be uploaded to our cloud. Please note our ");
        Anchor policyLink = new Anchor(
                "https://vaadin.com/privacy-policy",
                "privacy policy", AnchorTarget.BLANK
        );

        return new Span(cloudHint, policyLink);
    }

}

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 or not
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 or not (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

Event

Description

All Finished

Triggered when Upload has processed all the files in its queue, regardless of whether all the uploads were successful or not

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 or not (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

Labelling

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’re using a screen reader as the button’s label is read aloud when focused.

Open in a
new tab

Source code

UploadLabelling.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.notification.Notification;
import com.vaadin.flow.component.notification.NotificationVariant;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-labelling")
public class UploadLabelling extends Div {

    public UploadLabelling() {
        MemoryBuffer buffer = new MemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setAcceptedFileTypes("application/pdf", ".pdf");

        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getAddFiles().setOne("Upload PDF...");
        i18n.getDropFiles().setOne("Drop PDF here");
        i18n.getError()
                .setIncorrectFileType(
                        "The provided file does not have the correct format. Please provide a PDF document.");
        upload.setI18n(i18n);
        // end::snippet[]

        upload.addFileRejectedListener(event -> {
            String errorMessage = event.getErrorMessage();

            Notification notification = Notification.show(
                    errorMessage,
                    5000,
                    Notification.Position.MIDDLE
            );
            notification.addThemeVariants(NotificationVariant.LUMO_ERROR);
        });

        add(upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
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.

Open in a
new tab

Source code

UploadHelper.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H4;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.notification.Notification;
import com.vaadin.flow.component.notification.NotificationVariant;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-helper")
public class UploadHelper extends Div {

    public UploadHelper() {
        MemoryBuffer buffer = new MemoryBuffer();
        // tag::snippet[]
        H4 title = new H4("Upload spreadsheet");
        Paragraph hint = new Paragraph(
                "File size must be less than or equal to 1 MB. Only Excel and CSV files are accepted.");

        Upload upload = new Upload(buffer);
        upload.setAcceptedFileTypes(
                // Microsoft Excel (.xls)
                "application/vnd.ms-excel",
                ".xls",
                // Microsoft Excel (OpenXML, .xlsx)
                "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                ".xlsx",
                // Comma-separated values (.csv)
                "text/csv",
                ".csv"
        );

        UploadExamplesI18N i18n = new UploadExamplesI18N();
        i18n.getAddFiles().setOne("Upload Spreadsheet...");
        i18n.getDropFiles().setOne("Drop spreadsheet here");
        i18n.getError()
                .setIncorrectFileType(
                        "Please provide the file in one of the supported formats (.xls, .xlsx, .csv).");
        upload.setI18n(i18n);

        add(title, hint, upload);
        // end::snippet[]

        title.getStyle().set("margin-top", "0");
        hint.getStyle().set("color", "var(--lumo-secondary-text-color)");

        upload.addFileRejectedListener(event -> {
            String errorMessage = event.getErrorMessage();

            Notification notification = Notification.show(
                    errorMessage,
                    5000,
                    Notification.Position.MIDDLE
            );
            notification.addThemeVariants(NotificationVariant.LUMO_ERROR);
        });

    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
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.

Open in a
new tab

Source code

UploadErrorMessages.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.formlayout.FormLayout;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Label;
import com.vaadin.flow.component.upload.Upload;
import com.vaadin.flow.component.upload.receivers.MultiFileMemoryBuffer;
import com.vaadin.flow.router.Route;

@Route("upload-error-messages")
public class UploadErrorMessages extends Div {

    public UploadErrorMessages() {
        Div cautionExample = setupCautionExample();
        Div recommendedExample = setupRecommendedExample();

        FormLayout formLayout = new FormLayout(cautionExample, recommendedExample);
        formLayout.setResponsiveSteps(new FormLayout.ResponsiveStep("0", 1),
                                      new FormLayout.ResponsiveStep("540px", 2));

        add(formLayout);
    }

    private Div setupCautionExample() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        Upload upload = new Upload(buffer);
        upload.setDropAllowed(false);

        UploadExamplesI18N i18N = new UploadExamplesI18N();
        i18N.getUploading()
                .getError()
                .setUnexpectedServerError("Unexpected Server Error");
        upload.setI18n(i18N);

        Label label = new Label("Caution");
        label.getStyle().set("font-weight", "600");
        upload.setId("upload-caution");
        label.setFor(upload.getId().get());

        return new Div(label, upload);
    }

    private Div setupRecommendedExample() {
        MultiFileMemoryBuffer buffer = new MultiFileMemoryBuffer();
        // tag::snippet[]
        Upload upload = new Upload(buffer);
        upload.setDropAllowed(false);

        UploadExamplesI18N i18N = new UploadExamplesI18N();
        i18N.getUploading()
                .getError()
                .setUnexpectedServerError(
                        "File couldn't be uploaded, please try again later");
        upload.setI18n(i18N);
        // end::snippet[]

        Label label = new Label("Recommended");
        label.getStyle().set("font-weight", "600");
        upload.setId("upload-recommended");
        label.setFor(upload.getId().get());

        return new Div(label, upload);
    }

}
UploadExamplesI18N.javapackage com.vaadin.demo.component.upload;

import com.vaadin.flow.component.upload.UploadI18N;

import java.util.Arrays;

/**
 * Provides a default I18N configuration for the Upload examples
 *
 * At the moment the Upload component requires a fully configured I18N
 * instance, even for use-cases where you only want to change individual texts.
 *
 * This I18N configuration is an adaption of the web components I18N defaults
 * and can be used as a basis for customizing individual texts.
 */
public class UploadExamplesI18N extends UploadI18N {
    public UploadExamplesI18N() {
        setDropFiles(new DropFiles()
                .setOne("Drop file here")
                .setMany("Drop files here"));
        setAddFiles(new AddFiles()
                .setOne("Upload File...")
                .setMany("Upload Files..."));
        setCancel("Cancel");
        setError(new Error()
                .setTooManyFiles("Too Many Files.")
                .setFileIsTooBig("File is Too Big.")
                .setIncorrectFileType("Incorrect File Type."));
        setUploading(new Uploading()
                .setStatus(new Uploading.Status()
                        .setConnecting("Connecting...")
                        .setStalled("Stalled")
                        .setProcessing("Processing File...")
                        .setHeld("Queued"))
                .setRemainingTime(new Uploading.RemainingTime()
                        .setPrefix("remaining time: ")
                        .setUnknown("unknown remaining time"))
                .setError(new Uploading.Error()
                        .setServerUnavailable("Upload failed, please try again later")
                        .setUnexpectedServerError("Upload failed due to server error")
                        .setForbidden("Upload forbidden")));
        setUnits(new Units()
                .setSize(Arrays.asList("B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")));
    }
}
UploadExamplesI18N.java

Progress Bar

Component for showing task completion progress.

767444F7-AAC8-433D-BE67-6BFE29FB4976

Docs

Docs

Upload

Handling Uploaded Files

Drag & Drop

Auto Upload

Upload Restrictions

File Format

File Count

File Size

File Actions

Internationalization (i18n)

Customization

Technical

Listeners

Best Practices

Labelling

Error Messages

Docs

Handling Uploaded Files

Drag & Drop

Auto Upload

Upload Restrictions

File Format

File Count

File Size

File Actions

Internationalization (i18n)

Customization

Technical

Listeners

Best Practices

Labelling

Error Messages

Related Components