Progress Bar

Source

<script setup lang="ts">
import { ref } from "vue";
import MtProgressBar from "@shopware-ag/meteor-component-library/MtProgressBar";

const value = ref(45);
</script>

<template>
  <mt-progress-bar v-model="value" :max-value="100" label="Upload progress" />
</template>

Usage

Progress Bar is a determinate indicator for tasks such as uploads, imports, or processing steps where completion can be measured. Use it when you can communicate a meaningful current value and maximum value, placed in context close to the content or action the progress belongs to.

import { MtProgressBar } from "@shopware-ag/meteor-component-library";

Examples

Custom units and error

<script setup lang="ts">
import { ref } from "vue";
import MtProgressBar from "@shopware-ag/meteor-component-library/MtProgressBar";

const uploadedSize = ref(277);
</script>

<template>
  <mt-progress-bar
    v-model="uploadedSize"
    :max-value="356"
    label="Upload progress"
    progress-label-type="kb"
    :error="{ code: 500, detail: 'Error while loading' }"
  />
</template>

API reference

Props

Prop	Type	Default
`label` *	`string`
`max-value` *	`number`
`error`	`{ detail: string; code: number; } \| null`
`progress-label-type`	`string`	`"percent"`
`model-value`	`number`

Events

Event	Payload
`update:modelValue`	`[value: number \| undefined]`

Best practices

Provide a clear label so users understand what the progress refers to.
Keep the value and maximum meaningful, stable, and easy to reason about.
Use the default percentage label when percent is the clearest way to communicate progress.
Use progressLabelType when a concrete unit such as kb or items is more useful than a percentage.
Show the error state when progress is blocked or the related process fails.

Don't

Do not use Progress Bar when the task has no measurable completion state.
Do not rely on progress color alone to communicate success or failure.
Do not feed invalid values on purpose and rely on clamping as the primary behavior.
Do not hide the surrounding context for long-running tasks that may need more explanation.

Behavior

Progress Bar uses the current value and maxValue to calculate the filled width.
The fill width is clamped between 0% and 100%, so values below 0 or above the maximum do not overflow the track.
By default the progress label is shown as a percentage. When progressLabelType is set to another value, the label is rendered as current unit / max unit.
When error is present, the fill changes to the critical color and the error message is rendered below the track.

Accessibility

Progress Bar exposes role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax.
Provide a visible label, because the progressbar is associated with that label via aria-labelledby.
The percentage or unit label is marked aria-hidden, so important status information should not depend on that text alone.
If the task is especially important or long-running, pair Progress Bar with additional explanatory text so screen-reader and keyboard users have enough context.

Loader: when work is in progress but the exact completion amount is unknown.

Edit this pageorReport an issue

Popover

An experimental floating surface that reveals contextual settings and nested option views from a trigger.

Promo Badge

A specialized Badge for predefined promotional labels such as New, Beta, or Shopware AI.