> Markdown version of [Progress Bar](https://vaadin.com/docs/v24/components/progress-bar). Section index: [llms.txt](https://vaadin.com/docs/v24/components/llms.txt)

# Progress Bar

Progress Bar shows the amount of completion 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.

**Lit** — `progress-bar-basic.ts`

```typescript
<vaadin-progress-bar value="0.5"></vaadin-progress-bar>
```

**Flow** — `ProgressBarBasic.java`

```java
ProgressBar progressBar = new ProgressBar();
progressBar.setValue(0.5);
add(progressBar);
```

**React** — `progress-bar-basic.tsx`

```tsx
<ProgressBar value={0.5} />
```

> **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 don’t need to provide an explicit Progress Bar for these situations.

## <a id="modes"></a>Modes

### <a id="determinate"></a>Determinate

Use a determinate Progress Bar when progress can be computed.

**Lit** — `progress-bar-determinate.ts`

```typescript
<div>
  <vaadin-progress-bar value="0.5"></vaadin-progress-bar>
</div>
```

**Flow** — `ProgressBarDeterminate.java`

```java
ProgressBar progressBar = new ProgressBar();
progressBar.setValue(0.5);
```

**React** — `progress-bar-determinate.tsx`

```tsx
<div>
  <ProgressBar value={0.5} />
</div>
```

### <a id="indeterminate"></a>Indeterminate

Use an indeterminate Progress Bar to show that progress is ongoing but can’t be computed.

**Lit** — `progress-bar-indeterminate.ts`

```typescript
<div>
  <vaadin-progress-bar indeterminate></vaadin-progress-bar>
</div>
```

**Flow** — `ProgressBarIndeterminate.java`

```java
ProgressBar progressBar = new ProgressBar();
progressBar.setIndeterminate(true);
```

**React** — `progress-bar-indeterminate.tsx`

```tsx
<div>
  <ProgressBar indeterminate />
</div>
```

## <a id="bounds-and-initial-value"></a>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:

**Lit** — `progress-bar-custom-range.ts`

```typescript
<div>
  <vaadin-progress-bar min="0" max="100" value="50"></vaadin-progress-bar>
</div>
```

**Flow** — `ProgressBarCustomRange.java`

```java
ProgressBar progressBar = new ProgressBar();
progressBar.setMin(0);
progressBar.setMax(100);
progressBar.setValue(50);
```

**React** — `progress-bar-custom-range.tsx`

```tsx
<div>
  <ProgressBar min={0} max={100} value={50} />
</div>
```

## <a id="theme-variants"></a>Theme Variants

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

**Lit** — `progress-bar-theme-variants.ts`

```typescript
<vaadin-progress-bar value="0.5" theme="contrast"></vaadin-progress-bar>
<vaadin-progress-bar value="0.75" theme="success"></vaadin-progress-bar>
<vaadin-progress-bar value="0.2" theme="error"></vaadin-progress-bar>
```

**Flow** — `ProgressBarThemeVariants.java`

```java
// Contrast
ProgressBar progressBarContrast = new ProgressBar();
progressBarContrast.addThemeVariants(ProgressBarVariant.LUMO_CONTRAST);
progressBarContrast.setValue(0.5);

// Success
ProgressBar progressBarSuccess = new ProgressBar();
progressBarSuccess.addThemeVariants(ProgressBarVariant.LUMO_SUCCESS);
progressBarSuccess.setValue(0.75);

// Error
ProgressBar progressBarError = new ProgressBar();
progressBarError.addThemeVariants(ProgressBarVariant.LUMO_ERROR);
progressBarError.setValue(0.2);
```

**React** — `progress-bar-theme-variants.tsx`

```tsx
<ProgressBar value={0.5} theme="contrast" />
<ProgressBar value={0.75} theme="success" />
<ProgressBar value={0.2} theme="error" />
```

| 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                                                                           |

## <a id="best-practices"></a>Best Practices

### <a id="provide-a-label"></a>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 a graphical representation, for example the percentage of completion, or the number of items processed.

**Lit** — `progress-bar-label.ts`

```typescript
<vaadin-horizontal-layout style="justify-content: space-between;">
  <label class="text-secondary" id="pblabel">Processing Financials.xlsx</label>
  <span class="text-secondary">50%</span>
</vaadin-horizontal-layout>

<vaadin-progress-bar aria-labelledby="pblabel" value="0.5"></vaadin-progress-bar>
```

**Flow** — `ProgressBarLabel.java`

```java
ProgressBar progressBar = new ProgressBar();
progressBar.setValue(0.5);

NativeLabel progressBarLabelText = new NativeLabel(
        "Processing Financials.xlsx");
progressBarLabelText.setId("pblabel");
// Associates the label with the progressbar for screen readers:
progressBar.getElement().setAttribute("aria-labelledby", "pblabel");

Span progressBarLabelValue = new Span("50%");
HorizontalLayout progressBarLabel = new HorizontalLayout(
        progressBarLabelText, progressBarLabelValue);
progressBarLabel.setJustifyContentMode(JustifyContentMode.BETWEEN);

add(progressBarLabel, progressBar);
```

**React** — `progress-bar-label.tsx`

```tsx
<HorizontalLayout style={{ justifyContent: 'space-between' }}>
  <label className="text-secondary" id="pblabel">
    Processing Financials.xlsx
  </label>

  <span className="text-secondary">50%</span>
</HorizontalLayout>

<ProgressBar aria-labelledby="pblabel" value={0.5} />
```

### <a id="state-switching"></a>State Switching

Switch from indeterminate to determinate if the progress becomes computable, and similarly from determinate to indeterminate if it becomes non-computable.

### <a id="estimate-completion-time"></a>Estimate Completion Time

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

**Lit** — `progress-bar-completion-time.ts`

```typescript
<div>
  <label class="text-secondary" id="pblbl">Generating report...</label>
  <vaadin-progress-bar
    indeterminate
    aria-labelledby="pblbl"
    aria-describedby="sublbl"
  ></vaadin-progress-bar>
  <span class="text-secondary text-xs" id="sublbl">
    Process can take upwards of 10 minutes
  </span>
</div>
```

**Flow** — `ProgressBarCompletionTime.java`

```java
ProgressBar progressBar = new ProgressBar();
progressBar.setIndeterminate(true);

NativeLabel progressBarLabel = new NativeLabel("Generating report...");
progressBarLabel.setId("pblbl");
progressBarLabel.addClassName(LumoUtility.TextColor.SECONDARY);

Span progressBarSubLabel = new Span(
        "Process can take upwards of 10 minutes");
progressBarSubLabel.setId("sublbl");
progressBarSubLabel.addClassNames(LumoUtility.TextColor.SECONDARY,
        LumoUtility.FontSize.XSMALL);

// Associates the labels with the bar programmatically, for screen
// readers:
progressBar.getElement().setAttribute("aria-labelledby", "pblbl");
progressBar.getElement().setAttribute("aria-describedby", "sublbl");

add(progressBarLabel, progressBar, progressBarSubLabel);
```

**React** — `progress-bar-completion-time.tsx`

```tsx
<div>
  <label className="text-secondary" id="pblbl">
    Generating report...
  </label>

  <ProgressBar indeterminate aria-labelledby="pblbl" aria-describedby="sublbl" />

  <span className="text-secondary text-xs" id="sublbl">
    Process can take upwards of 10 minutes
  </span>
</div>
```

### <a id="asynchronous-processes"></a>Asynchronous Processes

If the user is waiting for a process to finish, 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. See chapter [Handling Long-Running Tasks](https://vaadin.com/docs/v24/flow/advanced/long-running-tasks.md) for information on how to do that or how to use the Progress Bar to inform user about the progress of long-running tasks.

> **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.

### <a id="when-to-use"></a>When to Use

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

### <a id="placement"></a>Placement

A Progress Bar’s location in the UI implies 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 not operable during pending server requests.

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

## <a id="related-components"></a>Related Components

| Component                                                  | Usage recommendations          |
| ---------------------------------------------------------- | ------------------------------ |
| [Upload](https://vaadin.com/docs/v24/components/upload.md) | Component for uploading files. |

`D9791B20-24D0-4C8A-9530-4F84350E5F4F`