Progress Bar

TuiProgress is used to display the current progress of an operation, percentages of statistical data, or dashboard indicators. It supports three display forms: Linear (Bar), Circular (Circle), and Dashboard (Guage), and features built-in status colors and animation effects.

Basic Usage

Linear Progress Bar (Bar)

The default form. Use value to set the progress value (default 0-100).

• label: Sets the text for the left-side label.
• status: Sets the status color (success, warning, danger, etc.).

<template>
  <div class="demo-gap">
    <TuiProgress :value="30" label="Basic Progress" />
    <TuiProgress :value="50" label="Completed" status="success" />
    <TuiProgress :value="70" label="Warning" status="warning" />
    <TuiProgress :value="90" label="Error" status="danger" />
  </div>
</template>

Form Variants

Switch the display form using the type attribute.

Circular Progress Bar (Circle)

Set type="circle".

• icon: An icon can be displayed in the center of the circle.

<template>
  <TuiProgress type="circle" :value="30" label="Normal" />
  
  <TuiProgress 
    type="circle" 
    :value="75" 
    status="success" 
    icon="tui-icon ti-check" 
  />
</template>

Dashboard (Guage)

Set type="guage". Typically used for Dashboard displays.

<TuiProgress 
  type="guage" 
  :value="80" 
  :strokeWidth="12" 
  label="CPU Usage" 
/>

Values and Thresholds

Smart Thresholds

Through the thresholds attribute, colors and statuses can change automatically based on the progress value. The object key is the status name (success, warning, etc.), and the value is the numerical node that triggers that status.

<script setup>
// Define thresholds: 0-59 is danger, 60-119 is warning, 120+ is success
const myThresholds = {
  danger: 59,
  warning: 119,
  success: 260
};
</script>

<template>
  <TuiProgress 
    :value="currentValue" 
    :maxValue="300" 
    :thresholds="myThresholds" 
    unit="Tons"
  />
</template>

Content Formatting (Format)

Customize the text content on the right or in the center via the format function or slots.

<script setup>
const formatText = (props) => {
  if (props.value === 100) return 'Full';
  return `${props.value}%`;
};
</script>

<template>
  <TuiProgress :value="100" :format="formatText" />

  <TuiProgress :value="60">
    <template #default="{ value }">
      <span style="color: blue">{{ value }} / 100 Points</span>
    </template>
  </TuiProgress>
</template>

Layout and Appearance

Label Layout

• labelNewline: Whether the label occupies a single line above the progress bar.
• labelWidth: Fixed label width, used for multi-line alignment.

<TuiProgress :value="40" label="Long title with automatic line break" labelNewline />

Internal Display (Value Inside)

For linear progress bars, setting valuePosition="inside" displays the percentage value inside the progress bar.

<TuiProgress :value="70" :strokeWidth="18" valuePosition="inside" />

Animations and Special Effects

• striped: Enables the striped effect.
• stripedFlow: Enables the flowing stripe animation (commonly used for loading).
• indeterminate: Enables the loading animation for indeterminate progress.

<TuiProgress :value="50" status="warning" striped stripedFlow />
<TuiProgress :value="30" indeterminate />

API Reference

Props

Property	Type	Default	Description
value	Number	0	Required. Current progress value.
type	String	'bar'	Type. Options: bar, circle, guage.
status	String	-	Status. Options: normal, success, danger, warning, emphasis, critical.
maxValue	Number	0	Maximum value (used to calculate ratio). Defaults to 100 if not set.
thresholds	Object	-	Threshold configuration object { status: number }.
color	String	-	Custom progress bar color (overrides status).
strokeWidth	Number	-	Progress bar width (px).
width	Number	-	Canvas width (used for Circle/Guage).
indeterminate	Boolean	false	Whether to use indeterminate progress animation.
striped	Boolean	false	Whether to display stripes.
stripedFlow	Boolean	false	Whether stripes flow.
strokeLinecap	String	'round'	End cap shape. Options: butt, round, square.
label	String	-	Label text on the left/top.
labelNewline	Boolean	false	Whether the label is displayed on a new line.
labelWidth	Number	-	Fixed width of the label area.
showValue	Boolean	true	Whether to display numerical values.
valuePosition	String	'default'	Value position. Options: default, newline, inside.
format	Function	-	Content formatting function (props) => string.
unit	String	-	Numerical value unit suffix.
icon	String	-	Icon class name.
showStatusIcon	Boolean	true	Whether to show the icon corresponding to the status (e.g., checkmark, exclamation mark).

Slots

Slot Name	Description	Parameters
default	Customize the content of the progress numerical area.	{ value }
label	Customize the content of the label area.	-
icon	Customize the content of the icon area.	-