引入

import { ProgressBar, Label } from '@heroui/react';

用法

加载中60%

import {Label, ProgressBar} from "@heroui/react";

export function Basic() {
  return (
    <ProgressBar aria-label="加载中" className="w-64" value={60}>

组件结构

import { ProgressBar, Label } from '@heroui/react';

export default () => (
  <ProgressBar value={60}>
    <Label>Loading</Label>
    <ProgressBar.Output />
    <ProgressBar.Track>
      <ProgressBar.Fill />
    </ProgressBar.Track>
  </ProgressBar>
);

尺寸

小40%

中60%

大80%

import {Label, ProgressBar} from "@heroui/react";

const SIZE_LABELS = {
  lg: "大",
  md: "中",

颜色

默认50%

强调50%

成功50%

警告50%

危险50%

import {Label, ProgressBar} from "@heroui/react";

const colors = ["default", "accent", "success", "warning", "danger"] as const;

const COLOR_LABELS: Record<(typeof colors)[number], string> = {

不确定进度

在无法确定具体进度时，使用 isIndeterminate。

加载中…

import {Label, ProgressBar} from "@heroui/react";

export function Indeterminate() {
  return (
    <ProgressBar isIndeterminate aria-label="加载中" className="w-64">

自定义数值范围

使用 minValue、maxValue 与 formatOptions 自定义取值范围与展示格式。

进度75%

选项

值

最小值

最大值

格式

"use client";

import {Label, ListBox, NumberField, ProgressBar, Select, Separator} from "@heroui/react";
import {useState} from "react";

无可见标签

不需要可见标签时，请使用 aria-label 保证无障碍。

import {ProgressBar} from "@heroui/react";

export function WithoutLabel() {
  return (
    <ProgressBar aria-label="加载进度" className="w-64" value={45}>

样式

传入 Tailwind CSS 类

你可以为 ProgressBar 的各个部分单独添加类名：

import { ProgressBar, Label } from '@heroui/react';

function CustomProgressBar() {
  return (
    <ProgressBar value={60}>
      <Label>Loading</Label>
      <ProgressBar.Output />
      <ProgressBar.Track className="bg-purple-100 dark:bg-purple-900">
        <ProgressBar.Fill className="bg-purple-500" />
      </ProgressBar.Track>
    </ProgressBar>
  );
}

自定义组件类

要自定义 ProgressBar 的组件类，可使用 @layer components 指令。
了解更多.

@layer components {
  .progress-bar {
    @apply w-full gap-2;
  }

  .progress-bar__track {
    @apply h-3 rounded-full;
  }

  .progress-bar__fill {
    @apply rounded-full;
  }
}

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

ProgressBar 使用以下 CSS 类（查看源码样式）：

基础与元素类

.progress-bar - 基础容器（网格布局）
.progress-bar__output - 数值文本展示
.progress-bar__track - 轨道背景
.progress-bar__fill - 轨道上已填充部分

尺寸类

.progress-bar--sm - 小尺寸变体（更细的轨道）
.progress-bar--md - 中等尺寸变体（默认）
.progress-bar--lg - 大尺寸变体（更粗的轨道）

颜色类

.progress-bar--default - 默认颜色变体
.progress-bar--accent - 强调色变体
.progress-bar--success - 成功色变体
.progress-bar--warning - 警告色变体
.progress-bar--danger - 危险色变体

API 参考

ProgressBar Props

继承自 React Aria ProgressBar。

Prop	类型	默认值	描述
`value`	`number`	`0`	当前值
`minValue`	`number`	`0`	最小值
`maxValue`	`number`	`100`	最大值
`isIndeterminate`	`boolean`	`false`	是否为不确定进度
`size`	`"sm" \| "md" \| "lg"`	`"md"`	进度轨道尺寸
`color`	`"default" \| "accent" \| "success" \| "warning" \| "danger"`	`"accent"`	填充条颜色
`formatOptions`	`Intl.NumberFormatOptions`	`{style: 'percent'}`	数值展示的数字格式
`valueLabel`	`ReactNode`	-	自定义数值标签内容
`children`	`ReactNode \| (values: ProgressBarRenderProps) => ReactNode`	-	内容或渲染 prop

ProgressBarRenderProps

使用渲染 prop 模式时，会提供以下值：

Prop	类型	描述
`percentage`	`number`	进度百分比（0–100）
`valueText`	`string`	格式化后的数值文本
`isIndeterminate`	`boolean`	是否为不确定进度

ProgressBar 进度条

引入

用法