Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Progress Bar

Progress Bar shows the completion status of a task or process. The progress can be determinate or indeterminate. Use Progress Bar to show an ongoing process that takes a noticeable time to finish.

Open in a
new tab
ProgressBar progressBar = new ProgressBar();
progressBar.setValue(0.5);
add(progressBar);
Note
Global loading indicator
A global loading indicator shows at the top of the viewport while processing a server request, after a configurable delay. You do not need to provide an explicit Progress Bar for these situations.

Modes

Determinate

Use a determinate Progress Bar when progress can be computed.

Open in a
new tab
ProgressBar progressBar = new ProgressBar();
progressBar.setValue(0.5);

Div progressBarLabel = new Div();
progressBarLabel.setText("Processing Financials.xlsx (50%)");

add(progressBarLabel, progressBar);

Indeterminate

Use an indeterminate Progress Bar to show that progress is ongoing but cannot be computed.

Open in a
new tab
ProgressBar progressBar = new ProgressBar();
progressBar.setIndeterminate(true);

Div progressBarLabel = new Div();
progressBarLabel.setText("Generating report...");

add(progressBarLabel, progressBar);

Bounds and Initial Value

The progress value defaults to a range from 0 to 1, with an initial value of 0. These can be changed to any numeric values:

Open in a
new tab
ProgressBar progressBar = new ProgressBar();
progressBar.setMin(0);
progressBar.setMax(100);
progressBar.setValue(50);

Div progressBarLabel = new Div();
progressBarLabel.setText("Processing files (50/100)");

add(progressBarLabel, progressBar);

Theme Variants

Progress Bar comes with three theme variants: contrast, success and error.

Open in a
new tab
ProgressBar progressBarContrast = new ProgressBar();
progressBarContrast.addThemeVariants(ProgressBarVariant.LUMO_CONTRAST);
Variant Theme name Usage recommendations

Success

success

* When progress is satisfactory and/or nearing completion

* Visual preference

Error

error

* When progress is unsatisfactory

* Draw the user’s attention to a stalled or failed process

Contrast

contrast

* Visual preference

Best Practices

Provide a Label

Use labels to give context to a Progress Bar. Labels can also show the progress of a determinate progress bar in text in addition to graphical representation, for example, completion percentage or number of items processed.

Open in a
new tab
ProgressBar progressBar = new ProgressBar();
progressBar.setValue(0.5);

Div progressBarLabelText = new Div();
progressBarLabelText.setText("Processing Financials.xlsx");
Div progressBarLabelValue = new Div();
progressBarLabelValue.setText("50%");
FlexLayout progressBarLabel = new FlexLayout();
progressBarLabel.setJustifyContentMode(JustifyContentMode.BETWEEN);
progressBarLabel.add(progressBarLabelText, progressBarLabelValue);

add(progressBarLabel, progressBar);

State Switching

Switch from indeterminate to determinate if the progress becomes computable, and vice versa.

Estimate Completion Time

Provide estimates when possible. If a process takes approximately 20 minutes communicate that to the user.

Open in a
new tab
ProgressBar progressBar = new ProgressBar();
progressBar.setIndeterminate(true);

Div progressBarLabel = new Div();
progressBarLabel.setText("Generating report, please wait...");

Div progressBarSubLabel = new Div();
progressBarSubLabel.getStyle().set("font-size", "var(--lumo-font-size-xs)");
progressBarSubLabel.setText("Process can take upwards of 10 minutes");

add(progressBarLabel, progressBar, progressBarSubLabel);

Asynchronous Processes

If the user is waiting for a process to finish use, consider using a Notification to notify them upon its completion and/or failure. This is useful if the processing takes place “off-screen” or the user is doing other work while waiting.

Note
Avoid blocking processes
Use asynchronous processes whenever possible so as not to block the user from completing other tasks while waiting for the process to finish.

When to Use

If a back-end process takes longer than 1 second, use a Progress Bar to show to the user that something is happening, especially if it blocks the user’s workflow.

Placement

A Progress Bar’s location in the UI indicates to the user its scope and whether the surrounding UI is operable during its progression.

For example, a Vaadin application’s built-in loading indicator is placed at the top of the viewport to show that it affects the entire application. The UI is generally not operable during pending server requests.

Placing a Progress Bar in a dialog, details panel or an otherwise defined section, indicates that the process displayed is specific to that section. Depending on the user case, the user may or may not be able to interact with the UI.

Component Usage recommendations

Upload

Component for uploading files.

DBD22658-5DD8-451F-B059-D1B944ECAC35