Naive UI Progress Component

Progress component displays the completion status of an operation or task.

When to Use

Use this component when:

• File operations: Show upload/download progress
• Task completion: Display task or process progress
• Loading states: Indicate loading status
• Data visualization: Show percentage-based metrics

When to Invoke

Invoke this skill when:

• User needs to implement progress indicators
• User wants to show completion percentage
• User needs circular or linear progress bars
• User asks about progress customization
• User wants to display multiple progress indicators

Features

• Multiple Types: Line, circle, multiple-circle, and dashboard types
• Status Indicators: Default, info, success, warning, error statuses
• Customizable Appearance: Control color, height, border-radius
• Custom Indicator: Replace default percentage display
• Gradient Support: Linear gradient colors for progress

API Reference

Progress Props

Name	Type	Default	Description	Version
border-radius	number | string	undefined	Line progress's border-radius.
circle-gap	number	1	The gap between circles for multiple-circle type.
color	string | string[] | { stops: string[] } | Array<{ stops: string[] }>	undefined	Progress color. Supports gradient.	stops since 2.40.2
fill-border-radius	number | string	undefined	Line progress's fill border-radius.
gap-degree	number	75	The gap degree of half circle, 0 ~ 360.	2.25.2
gap-offset-degree	number	0	The gap offset degree.	2.25.2
height	number	undefined	Line progress's height.
indicator-placement	'inside' | 'outside'	'outside'	Indicator placement.
indicator-text-color	string	undefined	Indicator text color.
offset-degree	number	0	Offset degree of circular progress.	2.24.0
percentage	number | number[]	0	Percentage value.
processing	boolean	false	Processing status.
rail-color	string | string[]	undefined	Rail color.
rail-style	string | CSS | Array<string | CSS>	undefined	Rail style.
show-indicator	boolean	true	Whether to display indicators.
status	'default' | 'success' | 'error' | 'warning' | 'info'	'default'	Progress status.
stroke-width	number	7	Progress width.
type	'line' | 'circle' | 'multiple-circle' | 'dashboard'	line	Progress type.	'dashboard' 2.25.2
unit	string	%	Progress unit.

Progress Slots

Name	Parameters	Description
default	()	Content will replace default indicator content.

Basic Usage

Line Progress

<template>
  <n-space vertical>
    <n-progress type="line" :percentage="percentage" />
    <n-progress type="line" :percentage="percentage" :show-indicator="false" />
    <n-progress type="line" :percentage="percentage" indicator-placement="inside" />
    <n-space>
      <n-button @click="minus">Minus 10%</n-button>
      <n-button @click="add">Add 10%</n-button>
    </n-space>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const percentage = ref(50)

const add = () => {
  percentage.value = Math.min(100, percentage.value + 10)
}

const minus = () => {
  percentage.value = Math.max(0, percentage.value - 10)
}
</script>

Circle Progress

<template>
  <n-space>
    <n-progress type="circle" :percentage="percentage" />
    <n-progress type="circle" status="info" :percentage="percentage" />
    <n-progress type="circle" status="success" :percentage="percentage" />
    <n-progress type="circle" status="warning" :percentage="percentage" />
    <n-progress type="circle" status="error" :percentage="percentage" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const percentage = ref(75)
</script>

Common Patterns

Different Statuses

<template>
  <n-space vertical>
    <n-progress type="line" status="default" :percentage="60" />
    <n-progress type="line" status="info" :percentage="60" />
    <n-progress type="line" status="success" :percentage="60" />
    <n-progress type="line" status="warning" :percentage="60" />
    <n-progress type="line" status="error" :percentage="60" />
  </n-space>
</template>

Dashboard Type

<template>
  <n-space>
    <n-progress type="dashboard" gap-position="bottom" :percentage="80" />
    <n-progress
      type="dashboard"
      :gap-offset-degree="120"
      :gap-degree="120"
      :percentage="80"
    />
  </n-space>
</template>

Multiple Circle

<template>
  <n-progress
    type="multiple-circle"
    :stroke-width="6"
    :circle-gap="0.5"
    :percentage="[60, 40, 20]"
    :color="['#2080f0', '#18a058', '#f0a020']"
  />
</template>

Custom Indicator

<template>
  <n-progress type="circle" :percentage="20">
    <span style="text-align: center">20% is small</span>
  </n-progress>
  <n-progress type="line" status="success" :percentage="20">
    Don't put too much content here.
  </n-progress>
</template>

Custom Colors

<template>
  <n-progress
    type="circle"
    :percentage="20"
    color="#18a058"
    rail-color="rgba(24, 160, 88, 0.2)"
  />
  <n-progress
    type="line"
    :color="{ stops: ['white', 'pink'] }"
    :percentage="60"
  />
</template>

No Indicator

<template>
  <n-progress
    type="circle"
    :show-indicator="false"
    :percentage="20"
  />
  <n-progress
    type="line"
    :show-indicator="false"
    :percentage="20"
  />
</template>

Custom Height and Border Radius

<template>
  <n-space vertical>
    <n-progress
      type="line"
      :percentage="50"
      :height="24"
      :border-radius="4"
      :fill-border-radius="0"
    />
    <n-progress
      type="line"
      status="error"
      :percentage="50"
      :height="24"
      border-radius="12px 0 12px 0"
      fill-border-radius="12px 0 12px 0"
    >
      A Kind of Art
    </n-progress>
  </n-space>
</template>

Processing Animation

<template>
  <n-progress
    type="line"
    :percentage="60"
    indicator-placement="inside"
    processing
  />
</template>

Offset Degree

<template>
  <n-progress type="circle" :percentage="80" :offset-degree="120" />
</template>

Linear Gradient

<template>
  <n-flex vertical>
    <n-progress
      type="line"
      :percentage="percentage"
      :show-indicator="false"
      :color="{ stops: ['white', 'pink'] }"
    />
    <n-flex>
      <n-progress
        type="circle"
        :percentage="percentage"
        :color="{ stops: ['#E3F2FD', '#2080f0'] }"
      />
    </n-flex>
  </n-flex>
</template>

<script setup>
import { ref } from 'vue'

const percentage = ref(70)
</script>

Best Practices

1. Choose appropriate type: Use line for horizontal space, circle for compact displays

2. Use meaningful status: Match status with operation result (success, error, etc.)

3. Custom indicator for context: Replace percentage with meaningful text when appropriate

4. Consider height: Adjust height based on visual hierarchy

5. Use processing for indeterminate: Enable processing for ongoing operations

6. Multiple circles for comparison: Use multiple-circle to show related metrics