Note

This documentation describes the ProgressBar Vue component for native UI views for Xml templates see progress-bar.

ProgressBar

A horizontal progress indicator with determinate and indeterminate modes, built directly on plain HTML/CSS (no external UI library dependency).

Import

import { ProgressBar } from '@neos/design-system'

Props

Prop	Type	Default	Description
value	number \| undefined	undefined	Progress percentage (0-100). Used in determinate mode
showValue	boolean	true	Show the percentage value label inside the bar
mode	'determinate' \| 'indeterminate'	'determinate'	'indeterminate' animates continuously without a specific value
valueBackground	string \| undefined	undefined	Fill color for this instance, overriding the theme's default fill color when set
cornerRadius	'none' \| 'extrasmall' \| 'small' \| 'medium' \| 'large' \| 'extralarge' \| 'full' \| undefined	undefined	Corner radius for this instance (applies to both track and fill), overriding the theme's default when set - same tokens as style:corner-radius
labelColor	string \| undefined	undefined	Percentage label color for this instance when the label is inside the fill, overriding the theme's default when set
labelOutsideColor	string \| undefined	undefined	Percentage label color for this instance when the label is outside the fill, on the track
labelSize	'extrasmall' \| 'small' \| 'medium' \| 'large' \| 'extralarge' \| number	'medium'	Percentage label font size: a predefined theme value, or a hardcoded pixel number for a one-off override (same convention as Text's size prop)

Remarks

The track's own background color and corner radius can already be set per instance without a dedicated prop, by styling the component's root element directly (e.g. a wrapping element's style or a parent-scoped CSS rule) — valueBackground, cornerRadius, labelColor, and labelOutsideColor above exist specifically because the fill and the label are internal to the component and have no other way to be targeted per instance. cornerRadius accepts the same token vocabulary as style:corner-radius, not an arbitrary CSS value.

When the fill is too narrow to contain the percentage label, the label automatically moves outside the fill and renders on the track instead of being clipped or invisible. Since the label then sits on the track's background rather than the fill's, labelColor (used while inside the fill) and labelOutsideColor (used once outside) can be set to different values to keep the label readable in both positions.

labelSize follows the same convention as Text's own size prop: a predefined value (extrasmall, small, medium, large, extralarge) selects one of the theme's configured sizes, while a hardcoded pixel number bypasses the theme entirely for a one-off override - an arbitrary CSS value like a rem string is not accepted.

Usage Examples

Determinate progress

<ProgressBar :value="uploadProgress" />

Hidden label

<ProgressBar :value="50" :show-value="false" />

Indeterminate (infinite animation)

<ProgressBar mode="indeterminate" />

In a file upload area

<VerticalLayout space="small">
  <Text>Uploading {{ fileName }}…</Text>
  <ProgressBar :value="uploadPercent" :show-value="true" />
</VerticalLayout>

Custom fill color per instance

<ProgressBar :value="50" value-background="#0f6e63" />

<ProgressBar v-for="grade in grades" :key="grade.id" :value="grade.percent" :value-background="grade.color" />

Custom corner radius and label color

<ProgressBar :value="50" corner-radius="none" label-color="#ffffff" />

Different label color inside vs. outside the fill

<ProgressBar :value="1" value-background="#0f6e63" label-color="#ffffff" label-outside-color="#111111" />

Custom label font size

<ProgressBar :value="50" label-size="large" />