Cards

卡片家族：Stat 统计 · Chart Stat 图表统计 · Financial 金融 · Project / Task / User 业务 · Activity 事件 · File 文件 · Highlight 高亮。

StatCard

基础统计卡，8 主题 × 2 尺寸，支持 icon / kebab / badge 变体。

Import

import {
  StatCard, ProgressStatCard, ImageStatCard,
  LineChartStatCard, WheelChartStatCard, BarChartStatCard,
  BalanceCard, DebitCard, CreditCard,
  ProgressCard, ProjectCard, TaskCard, UserCard,
  HighlightCard, ActivityCard, FileCard,
} from "@forge-ui/react";

Usage

必填 title + value，其余可选。

Total Revenue

$14,000

10%

+$150 today

1<StatCard
2  title="Total Revenue"
3  value="$14,000"
4  trend="10%"
5  subtitle="+$150 today"
6  theme="purple"
7  size="lg"
8  icon={<ChartSquareBoldDuotone size={20} />}
9/>

Themes

8 种主题色（white / dark / purple / blue / green / orange / yellow / cyan），这里示意 5 种。

Title

$1,000

10%

+$150 today

Title

$1,000

10%

+$150 today

Title

$1,000

10%

+$150 today

Title

$1,000

10%

+$150 today

Title

$1,000

10%

+$150 today

1<StatCard theme="white" ... />
2<StatCard theme="dark" ... />
3<StatCard theme="purple" ... />
4<StatCard theme="blue" ... />
5<StatCard theme="green" ... />

Sizes

sm 紧凑（dashboard 网格）/ lg 完整展开。

Title Here

$1,000

10%

+$150 today

Total Revenue

$14,000

10%

+$150 today

1<StatCard size="sm" ... />
2<StatCard size="lg" ... />

API

Attribute	Type	Default	Description
`title`	`string`	`—`	卡片标题。
`value`	`string`	`—`	主数据值。
`trend`	`string`	`—`	趋势百分比，会作为右上角 badge。
`subtitle`	`string`	`—`	底部描述文本。
`theme`	`'white' \| 'dark' \| 'purple' \| 'blue' \| 'green' \| 'orange' \| 'yellow' \| 'cyan'`	`'white'`	8 种主题色。
`size`	`'sm' \| 'lg'`	`'sm'`	紧凑或完整尺寸。
`icon`	`ReactNode`	`—`	左上角图标槽。
`badgeVariant`	`'greyBg' \| 'solid' \| 'opacity' \| 'white'`	`'greyBg'`	trend badge 外观。
`onKebabClick`	`() => void`	`—`	右上角三点菜单回调。

ProgressStatCard

StatCard 加上一条水平进度条，用于表达配额或进度。

Usage

继承 StatCard 所有字段，新增 progressValue 与 progressColor。

Active Users

1,250

12%

+150 today

1<ProgressStatCard
2  title="Active Users"
3  value="1,250"
4  trend="12%"
5  subtitle="+150 today"
6  theme="purple"
7  progressValue={65}
8  progressColor="yellow"
9/>

API

Attribute	Type	Default	Description
`title / value / trend / subtitle / theme / size / icon`	`同 StatCard`	`—`	基础字段与 StatCard 一致。
`progressValue`	`number`	`0`	进度条数值 0-100。
`progressColor`	`ProgressColor`	`'purple'`	进度条颜色。

Chart Stat Cards

三种带 mini chart 的统计卡：折线 / 甜甜圈 / 柱状。基础字段一致，chart 字段各不同。

LineChartStatCard

底部嵌入迷你折线，chartColor 决定线条色。

Total Revenue

$14,000

10%

+$150 today

1<LineChartStatCard chartColor="purple" ... />
2<WheelChartStatCard wheelPercent={75} wheelColor="blue" ... />
3<BarChartStatCard barColor="green" ... />

Attribute	Type	Default	Description
`title / value / subtitle`	`string`	`—`	基础文案。
`trend`	`string`	`—`	趋势文案，如 +10%。
`trendDirection`	`'up' \| 'down'`	`'up'`	趋势方向。
`theme`	`'white' \| 'dark' \| 'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'yellow' \| 'cyan'`	`'white'`	卡片主题色。
`size`	`'sm' \| 'lg'`	`'sm'`	卡片尺寸（无 md 档）。
`chartColor`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'yellow' \| 'cyan'`	`'purple'`	折线与渐变底色。
`chartDirection`	`'up' \| 'down'`	`'up'`	折线走势方向。

WheelChartStatCard

甜甜圈环形进度，wheelPercent 控制填充比例。

Storage Used

72%

Out of 1 TB

1<LineChartStatCard chartColor="purple" ... />
2<WheelChartStatCard wheelPercent={75} wheelColor="blue" ... />
3<BarChartStatCard barColor="green" ... />

Attribute	Type	Default	Description
`title / value / subtitle`	`string`	`—`	基础文案。
`trend`	`string`	`—`	趋势文案。
`trendDirection`	`'up' \| 'down'`	`'up'`	趋势方向。
`theme`	`'white' \| 'dark' \| 'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'yellow' \| 'cyan'`	`'white'`	卡片主题色。
`size`	`'sm' \| 'lg'`	`'sm'`	卡片尺寸（无 md 档）。
`wheelColor`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'yellow' \| 'cyan'`	`'purple'`	甜甜圈主色。
`wheelPercent`	`number`	`70`	0-100 填充百分比。

BarChartStatCard

迷你柱状图，barColor 控制柱色。

Sessions

12,480

vs last week

1<LineChartStatCard chartColor="purple" ... />
2<WheelChartStatCard wheelPercent={75} wheelColor="blue" ... />
3<BarChartStatCard barColor="green" ... />

Attribute	Type	Default	Description
`title / value / subtitle`	`string`	`—`	基础文案。
`trend`	`string`	`—`	趋势文案。
`trendDirection`	`'up' \| 'down'`	`'up'`	趋势方向。
`theme`	`'white' \| 'dark' \| 'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'yellow' \| 'cyan'`	`'white'`	卡片主题色。
`size`	`'sm' \| 'lg'`	`'sm'`	卡片尺寸（无 md 档）。
`barColor`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'yellow' \| 'cyan'`	`'purple'`	柱子主色。
`bars`	`number[]`	`[16,24,32,20,40]`	迷你柱状图数据数组。

ImageStatCard

大号统计卡，右侧挂头像组，强调团队场景。

Usage

avatars 为 URL 数组，右上角自动叠圈。

Total Revenue2 Jul - Today

$14,000

10%

+$150 today

1<ImageStatCard
2  title="Total Revenue"
3  subtitle="2 Jul - Today"
4  value="$14,000"
5  trend="10%"
6  trendSubtitle="+$150 today"
7  theme="purple"
8  avatars={[...]}
9/>

API

Attribute	Type	Default	Description
`title / subtitle / value / trend / theme`	`同 StatCard`	`—`	基础字段。
`trendSubtitle`	`string`	`—`	趋势下方的小字。
`avatars`	`string[]`	`—`	右侧用户头像组 URL 列表。
`onKebabClick`	`() => void`	`—`	kebab 回调。

Financial Cards

BalanceCard / DebitCard / CreditCard —— 三类金融展示卡，7 种主题色，Debit/Credit 再分 glow / gradient / flat 三种质感。

BalanceCard

余额卡 + Transfer/Request 动作。balanceHidden 可隐藏数字。

9821

Total Balance

$21,500

10%

+$150 today

1<BalanceCard balance="$21,500" trend="10%" theme="purple" cardNumber="9821" />
2<DebitCard balance="$1,200.00" cardNumber="9090" expiry="07/25" theme="blue" variant="glow" />
3<CreditCard cardNumber="9090" holderName="John Doe" expiry="07/25" theme="dark" variant="gradient" />

Attribute	Type	Default	Description
`title`	`string`	`'Total Balance'`	卡片标题。
`balance`	`string`	`—`	余额文本。
`trend / trendDirection`	`string / 'up' \| 'down'`	`— / 'up'`	右上角趋势。
`subtitle`	`string`	`—`	副文案。
`theme`	`'white' \| 'dark' \| 'purple' \| 'blue' \| 'green' \| 'orange' \| 'yellow' \| 'cyan'`	`'white'`	卡片主题色。
`balanceHidden`	`boolean`	`false`	是否遮掩数字（用 •• 替代）。
`cardNumber`	`string`	`—`	卡号末 4 位。
`cardIcon`	`string`	`—`	卡号旁的品牌 icon 图片 URL（24×24 渲染）。
`onTransfer / onRequest`	`() => void`	`—`	Transfer / Request 按钮回调。

DebitCard

借记卡，展示余额 + 卡号 + 有效期。variant 控制质感（glow / gradient / flat）。

Balance$1,200.00

**** 909007/25

1<BalanceCard balance="$21,500" trend="10%" theme="purple" cardNumber="9821" />
2<DebitCard balance="$1,200.00" cardNumber="9090" expiry="07/25" theme="blue" variant="glow" />
3<CreditCard cardNumber="9090" holderName="John Doe" expiry="07/25" theme="dark" variant="gradient" />

Attribute	Type	Default	Description
`balance`	`string`	`'$1,200.00'`	余额文本。
`cardNumber`	`string`	`'9090'`	卡号末 4 位。
`expiry`	`string`	`'07/25'`	有效期。
`theme`	`'dark' \| 'purple' \| 'blue' \| 'green' \| 'orange' \| 'yellow' \| 'cyan'`	`'dark'`	主题色（7 种，无 white）。
`variant`	`'glow' \| 'gradient' \| 'flat'`	`'glow'`	背景质感：发光 / 渐变 / 纯色。

CreditCard

信用卡，无余额字段，多一个 holderName 持卡人姓名。

Number**** **** **** 9090

NameJohn Doe

07/25

1<BalanceCard balance="$21,500" trend="10%" theme="purple" cardNumber="9821" />
2<DebitCard balance="$1,200.00" cardNumber="9090" expiry="07/25" theme="blue" variant="glow" />
3<CreditCard cardNumber="9090" holderName="John Doe" expiry="07/25" theme="dark" variant="gradient" />

Attribute	Type	Default	Description
`cardNumber`	`string`	`'9090'`	卡号末 4 位。
`holderName`	`string`	`'John Doe'`	持卡人姓名。
`expiry`	`string`	`'07/25'`	有效期。
`theme`	`'dark' \| 'purple' \| 'blue' \| 'green' \| 'orange' \| 'yellow' \| 'cyan'`	`'dark'`	主题色（7 种，无 white）。
`variant`	`'glow' \| 'gradient' \| 'flat'`	`'glow'`	背景质感：发光 / 渐变 / 纯色。

ProgressCard

带分项进度条的汇总卡，适合任务拆解 / 执行进度总览。

Usage

主进度 + items 分项，每项有独立颜色。

Task Progress

75%Updated today

Design

100%

Dev

60%

20%

1<ProgressCard title="Task Progress" value="75%" progress={75} items={[...]} />

API

Attribute	Type	Default	Description
`title / value / subtitle / theme`	`同 StatCard`	`—`	基础字段。
`progress`	`number`	`0`	主进度条 0-100。
`progressColor`	`string`	`'#7c3aed'`	主进度条颜色。
`items`	`{ label, value, color }[]`	`—`	下方分项进度列表。

ProjectCard / TaskCard

两个业务卡：ProjectCard 带 logo（320 宽），TaskCard 无 logo（256 宽）。其余字段类似。

ProjectCard

项目卡：左上 logo + 标题 + 描述 + 进度 + 成员。

In Progress

Website Redesign

Landing + marketing pages

Progress65%

21 Oct 2022

1<ProjectCard
2  title="Website Redesign"
3  description="Landing + marketing pages"
4  labelText="In Progress"
5  labelColor="purple"
6  progress={65}
7  progressColor="purple"
8  avatars={avatars}
9  date="21 Oct 2022"
10  onMenuClick={() => {}}
11/>

Attribute	Type	Default	Description
`logo`	`string`	`—`	左上方 48×48 logo 图片 URL。
`title`	`string`	`—`	项目标题（必填）。
`description`	`string`	`—`	项目描述（可选，最多 2 行）。
`labelText`	`string`	`—`	右上 label 文案。
`labelColor`	`string`	`'bg-fg-grey-700'`	label 背景色 class（Tailwind bg-*）。
`progress`	`number`	`0`	进度 0-100。
`progressColor`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'yellow' \| 'cyan' \| 'gray'`	`'purple'`	进度条主色。
`avatars`	`string[]`	`[]`	参与者头像 URL 列表。
`overflowCount`	`number`	`—`	尾部 +N 圆，传 > 0 时显示。
`date`	`string`	`—`	右下角日期文案。
`onMenuClick`	`() => void`	`—`	右上 kebab 回调，传后才显示。

TaskCard

任务卡：无 logo，label 在顶部独立一行，宽度 256，适合任务板列。

Label

Design review

Ship spec by EOW

Progress50%

21 Oct 2022

1<ProjectCard
2  title="Website Redesign"
3  description="Landing + marketing pages"
4  labelText="In Progress"
5  labelColor="purple"
6  progress={65}
7  progressColor="purple"
8  avatars={avatars}
9  date="21 Oct 2022"
10  onMenuClick={() => {}}
11/>

Attribute	Type	Default	Description
`title`	`string`	`—`	任务标题（必填）。
`description`	`string`	`—`	任务描述（可选）。
`labelText`	`string`	`—`	顶部 label 文案。
`labelColor`	`string`	`'bg-fg-red'`	label 背景色 class。
`progress`	`number`	`0`	进度 0-100。
`progressColor`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'yellow' \| 'cyan' \| 'gray'`	`'purple'`	进度条主色。
`avatars`	`string[]`	`[]`	参与者头像 URL 列表。
`overflowCount`	`number`	`—`	尾部 +N 圆。
`date`	`string`	`—`	右下角日期文案。
`onMenuClick`	`() => void`	`—`	右上 kebab 回调。

UserCard

个人卡，支持头像或首字母底色，展示姓名 + 徽章 + 自定义统计字段。

Usage

优先使用 avatar，退化到 initials。

Mohammad Karim

Pro

Level

12,091

Exp

$12,091

Linda Blair

Label

Level

12,091

1<UserCard
2  avatar="https://..."
3  name="Mohammad Karim"
4  badge={<Label color="purple" size="sm">Pro</Label>}
5  stats={[{ label: "Level", value: "12,091" }]}
6  onMenuClick={() => {}}
7/>

API

Attribute	Type	Default	Description
`avatar`	`string`	`—`	头像图片 URL；没有时传 initials。
`initials`	`string`	`—`	无头像时显示的姓名首字母。
`initialsColor`	`AvatarInitialColor`	`'purple'`	initials 背景色。
`name`	`string`	`—`	用户名。
`badge`	`ReactNode`	`—`	右上角标签，一般放 <Label />。
`stats`	`{ label: string; value: string }[]`	`—`	下方统计信息。
`onMenuClick`	`() => void`	`—`	kebab 回调。

FileCard

文件卡片，根据扩展名展示对应图标，支持 success / uploading / error 三种状态。

Usage

file 对象内带 state 决定视觉。

Report.doc

300 KB

Uploading.pdf

800 KB-

Uploading

Failed.zip

2 MB-

Failed

1<FileCard file={{ id: "1", name: "Report.doc", size: "300 KB" }} />
2<FileCard file={{ id: "2", name: "Upload.pdf", size: "800 KB", state: "uploading" }} />
3<FileCard file={{ id: "3", name: "Failed.zip", size: "2 MB", state: "error" }} onRetry={...} onRemove={...} />

API

Attribute	Type	Default	Description
`file`	`{ id, name, size, state? }`	`—`	文件数据，state 可为 success / uploading / error。
`onRetry`	`(id: string) => void`	`—`	error 态的重试回调。
`onRemove`	`(id: string) => void`	`—`	删除回调。

HighlightCard

高亮展示卡，主图 + 浮动注解 + 底部产品列表，常用于电商榜单。

Usage

annotations 数组项带 position，可绝对定位在主图上。

Top Product

JBL Earnote Pro 2340 Sales | $26,982

Logic Wireless Mouse

140 Sales

$17,678

PS Controller

105 Sales

$5,500

1<HighlightCard title="Top Product" theme="purple" image="..." annotations={[...]} products={[...]} />

API

Attribute	Type	Default	Description
`title`	`string`	`—`	卡片标题。
`theme`	`CardTheme`	`'purple'`	主题色。
`image`	`string`	`—`	主展示图 URL。
`annotations`	`{ label, value, position }[]`	`—`	图片上的浮动注解。
`products`	`{ image, name, subtitle?, value }[]`	`—`	下方的产品缩略图列表。

ActivityCard

事件流卡片，顶部事件类型 + 时间，中部标题描述，底部键值对。

Usage

按事件类型传不同 icon，metadata 为 label/value 对。

Meet schedule created James William

14 Jan 2025, 10:00

Meet TitleLorem ipsum dolor sit amet, consectetur adipiscing elit.

Date14 Feb 2025, 14:00

PurposeFollow Up

Call schedule created James William

14 Jan 2025, 10:00

Call TitleLorem ipsum dolor sit amet.

Date14 Feb 2025, 14:00

1<ActivityCard icon={...} title="Meet Title" metadata={[...]} ... />

API

Attribute	Type	Default	Description
`icon`	`ReactNode`	`—`	顶部类型图标。
`headerText`	`string`	`—`	顶部描述，如「Meet schedule created by James」。
`datetime`	`string`	`—`	顶部时间戳。
`avatar`	`string`	`—`	创建者头像。
`title / description`	`string`	`—`	正文标题与描述。
`metadata`	`{ label, value }[]`	`—`	底部键值对。
`onMenuClick`	`() => void`	`—`	kebab 回调。

看所有变体 →