List

列表族：ListItem / DescriptionItem / ListGroup / ContactItem / NotificationItem / ProfileCard。

ListItem

通用列表行，左 lead + 中标题副标题 + 右尾部 value / trend。

Import

import {
  ListItem, DescriptionItem, ListGroup,
  ContactItem, NotificationItem, ProfileCard,
} from "@forge-ui/react";

Usage

RevenueThis month

$24,50010%

1<ListItem
2  lead={{ kind: "icon", icon: <WalletBoldDuotone size={20} />, color: "purple" }}
3  title="Revenue"
4  subtitle="This month"
5  value="$24,500"
6  trend="10%"
7  trendDirection="up"
8/>

Lead Variants

3 种 lead：icon（圆形彩色图标）/ avatar（圆形头像）/ image（44×44 方形）。

Icon leadRound colored

Avatar leadOnline

Image leadSquare 44×44

1<ListItem lead={{ kind: "icon", icon, color: "purple" }} title="Icon lead" />
2<ListItem lead={{ kind: "avatar", src: avatar }} title="Avatar lead" subtitle="Online" />
3<ListItem lead={{ kind: "image", src: imgUrl }} title="Image lead" subtitle="Square 44×44" />

API

Attribute	Type	Default	Description
`lead`	`ListItemLead`	`—`	左侧槽，判别联合：icon / avatar / image 三种。
`title`	`string`	`—`	主标题，line-clamp-1。
`subtitle`	`string`	`—`	副标题。
`value`	`string`	`—`	右上 tail 文案（金额等）。
`trend`	`string`	`—`	右下趋势标签。
`trendDirection`	`'up' \| 'down'`	`'up'`	趋势方向，影响颜色和箭头。
`tailSubtext`	`string`	`—`	value 下方的辅助文案（与 trend 互斥）。
`trailing`	`ReactNode`	`—`	完全自定义右侧内容（覆盖 value/trend/tailSubtext）。

DescriptionItem

字段展示行：标签（灰）+ 主内容 + 可选 actions。用于详情页字段组。

Usage

Emailjane@example.com

1<DescriptionItem
2  label="Email"
3  content="jane@example.com"
4  lead={{ kind: "icon", icon: <LetterBoldDuotone size={20} />, color: "purple" }}
5/>

API

Attribute	Type	Default	Description
`lead`	`icon \| image`	`—`	左侧图标或方形图片。
`label`	`string`	`—`	字段标签（灰色）。
`content`	`ReactNode`	`—`	主内容，字符串会自动黑色 medium。
`actions`	`ReactNode`	`—`	右侧操作槽。

ListGroup

白底卡片容器，装一组 ListItem / DescriptionItem。Figma 两种预设：「Without Tab」纯列表 / 「With Tab」头部带 tab 切换。

Without Tab

纯列表模式：title + subtitle + badge + 一组 items。

Favorites3

Your saved items

Revenue

$24,500

Analytics

$12,000

Projects

1// Without Tab
2<ListGroup
3  title="Favorites"
4  subtitle="Your saved items"
5  badge={<Label color="purple">3</Label>}
6  items={<>...</>}
7/>

With Tab

头部嵌入 tab：传 tabs + activeTab + onTabChange 即可。

Activity

Payment received

$1,200

Report ready

View

1// With Tab
2<ListGroup
3  title="Activity"
4  tabs={[
5    { value: "all", label: "All" },
6    { value: "unread", label: "Unread" },
7  ]}
8  activeTab={tab}
9  onTabChange={setTab}
10  items={<>...</>}
11/>

API

Attribute	Type	Default	Description
`title`	`string`	`—`	组标题。
`subtitle`	`string`	`—`	副标题。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	tab 选中态主色。
`items`	`ReactNode`	`—`	列表主体（传一组 ListItem / DescriptionItem 等）。
`badge`	`ReactNode`	`—`	标题旁徽标槽。
`action`	`ReactNode`	`—`	右上角操作槽。
`tabs`	`{ value: string; label: string }[]`	`—`	可选 tab 数组，传后切换为「With Tab」模式。
`activeTab`	`string`	`—`	当前选中的 tab value（受控）。
`onTabChange`	`(value: string) => void`	`—`	tab 切换回调。
`closable`	`boolean`	`false`	是否渲染右上 close 按钮（覆盖 action 槽）。
`onClose`	`() => void`	`—`	close 回调。

ContactItem

IM 联系人行。头像 / 姓名 / 最新消息 / 时间 / 未读徽标 / 在线点。

Usage

Jane Cooper

See you tomorrow!

10:302

1<ContactItem avatar={avatar} name="Jane Cooper" message="See you tomorrow!" time="10:30" unreadCount={2} online />

API

Attribute	Type	Default	Description
`type`	`'person' \| 'team'`	`'person'`	person 渲染头像，team 渲染 initials 方块。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	active 态背景主色。
`name`	`string`	`—`	联系人姓名。
`message`	`string`	`—`	最新消息摘要。
`online`	`boolean`	`false`	绿色在线点。
`active`	`boolean`	`false`	选中态（主色背景）。
`unreadCount`	`number`	`—`	未读徽标，> 0 显示橙色 pill。
`time`	`string`	`—`	右上时间文案。

NotificationItem

通知中心单条。未读态浅黄背景，含 tag / time / title / body / Mark as Read。

Usage

System2h ago

Your order has been shipped

Tracking number: 1Z999AA10123456784

1<NotificationItem
2  tag="System"
3  time="2h ago"
4  title="Your order has been shipped"
5  body="Tracking number: 1Z999AA10123456784"
6  unread
7  onMarkRead={() => {}}
8/>

API

Attribute	Type	Default	Description
`tag`	`string`	`—`	顶部分类标签。
`time`	`string`	`—`	顶部时间。
`title`	`string`	`—`	通知标题。
`body`	`string`	`—`	通知正文。
`unread`	`boolean`	`false`	未读态：浅黄色背景。
`onMarkRead`	`() => void`	`—`	标记已读回调，传了才显示按钮。
`actionLabel`	`string`	`'Mark as Read'`	操作按钮文案。

ProfileCard

profile 选择器行。头像 + 姓名 + 副标题 + 下拉箭头，3 种 state。

Usage

1<ProfileCard avatar={avatar} name="Jane Cooper" subtitle="Admin" />
2<ProfileCard avatar={avatar} name="Selected" subtitle="Active" state="selected" />

API

Attribute	Type	Default	Description
`avatar`	`string`	`—`	头像 URL。
`name`	`string`	`—`	姓名。
`subtitle`	`string`	`—`	副标题（角色等）。
`state`	`'idle' \| 'hover' \| 'selected'`	`'idle'`	视觉状态。
`accent`	`'purple' \| 'blue' \| 'black'`	`'purple'`	selected 态主色。
`surface`	`'default' \| 'onColoredBg'`	`'default'`	onColoredBg 用于色底 sidebar 内，采用半透明白。

看所有变体 →