TagGroup 标签组

可聚焦的标签列表，支持键盘导航、选择与移除。

用法

1import { TagGroup } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3// Adapted from HeroUI v3.2.6 tag-group-basic (Apache-2.0).4import { PlanetEarth, Rocket, ShoppingBag, SquareArticle } from "@gravity-ui/icons";5import { Tag, TagGroup } from "@lenso/ui";6
7export function TagGroupBasic() {8  return (9    <TagGroup aria-label="Tags" selectionMode="single">10      <TagGroup.List>11        <Tag itemKey="default-news" textValue="News">12          <SquareArticle width={12} height={12} />13          News14        </Tag>15        <Tag itemKey="default-travel" textValue="Travel">16          <PlanetEarth width={12} height={12} />17          Travel18        </Tag>19        <Tag itemKey="default-gaming" textValue="Gaming">20          <Rocket width={12} height={12} />21          Gaming22        </Tag>23        <Tag itemKey="default-shopping" textValue="Shopping">24          <ShoppingBag width={12} height={12} />25          Shopping26        </Tag>27      </TagGroup.List>28    </TagGroup>29  );30}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

1import { TagGroup, Tag, Label, Description, ErrorMessage } from '@lenso/ui';2
3export default () => (4  <TagGroup>5    <Label />6    <TagGroup.List>7      <Tag>8        <Tag.RemoveButton />9      </Tag>10    </TagGroup.List>11    <Description />12    <ErrorMessage />13  </TagGroup>14)

示例

尺寸

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 sizes adaptation (Apache-2.0).3import * as stylex from "@stylexjs/stylex";4import { TagGroup } from "@lenso/ui";5import { Label } from "./text";6import { Categories, styles } from "./categories";7export function TagGroupSizes() {8  return (9    <div {...stylex.props(styles.sizes)}>10      {(["sm", "md", "lg"] as const).map((size, index) => (11        <TagGroup12          key={size}13          aria-label={["Small", "Medium", "Large"][index]}14          selectionMode="single"15          size={size}16        >17          <Label>{["Small", "Medium", "Large"][index]}</Label>18          <TagGroup.List>19            <Categories count={3} />20          </TagGroup.List>21        </TagGroup>22      ))}23    </div>24  );25}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

变体

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 variants adaptation (Apache-2.0).3import * as stylex from "@stylexjs/stylex";4import { TagGroup } from "@lenso/ui";5import { Label } from "./text";6import { Categories, styles } from "./categories";7export function TagGroupVariants() {8  return (9    <div {...stylex.props(styles.stack)}>10      {(["default", "surface"] as const).map((variant) => (11        <TagGroup12          key={variant}13          aria-label={variant === "default" ? "Default" : "Surface"}14          selectionMode="single"15          variant={variant}16        >17          <Label>{variant === "default" ? "Default" : "Surface"}</Label>18          <TagGroup.List>19            <Categories count={3} />20          </TagGroup.List>21        </TagGroup>22      ))}23    </div>24  );25}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 disabled adaptation (Apache-2.0).3import * as stylex from "@stylexjs/stylex";4import { TagGroup } from "@lenso/ui";5import { Description, Label } from "./text";6import { Categories, styles } from "./categories";7export function TagGroupDisabled() {8  return (9    <div {...stylex.props(styles.disabled)}>10      <TagGroup aria-label="Disabled Tags" selectionMode="single">11        <Label>Disabled Tags</Label>12        <TagGroup.List>13          <Categories disabled count={3} />14        </TagGroup.List>15        <Description>Some tags are disabled</Description>16      </TagGroup>17      <TagGroup18        aria-label="Disabled Keys"19        disabledKeys={new Set(["travel"])}20        selectionMode="single"21      >22        <Label>Disabled Keys</Label>23        <TagGroup.List>24          <Categories count={3} />25        </TagGroup.List>26        <Description>Tags disabled via disabledKeys prop</Description>27      </TagGroup>28    </div>29  );30}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

选择模式

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 selection-modes adaptation (Apache-2.0).3import { useState, type Key } from "react";4import * as stylex from "@stylexjs/stylex";5import { TagGroup } from "@lenso/ui";6import { Description, Label } from "./text";7import { Categories, styles } from "./categories";8export function TagGroupSelectionModes() {9  const [single, setSingle] = useState<Set<Key>>(new Set(["news"]));10  const [multiple, setMultiple] = useState<Set<Key>>(new Set(["news", "travel"]));11  return (12    <div {...stylex.props(styles.stack)}>13      <TagGroup14        aria-label="Single Selection"15        selectedKeys={single}16        selectionMode="single"17        onSelectionChange={setSingle}18      >19        <Label>Single Selection</Label>20        <TagGroup.List>21          <Categories />22        </TagGroup.List>23        <Description>Choose one category</Description>24      </TagGroup>25      <TagGroup26        aria-label="Multiple Selection"27        selectedKeys={multiple}28        selectionMode="multiple"29        onSelectionChange={setMultiple}30      >31        <Label>Multiple Selection</Label>32        <TagGroup.List>33          <Categories />34        </TagGroup.List>35        <Description>Choose multiple categories</Description>36      </TagGroup>37    </div>38  );39}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 controlled adaptation (Apache-2.0).3import { useState, type Key } from "react";4import { TagGroup } from "@lenso/ui";5import { Description, Label } from "./text";6import { Categories } from "./categories";7export function TagGroupControlled() {8  const [selected, setSelected] = useState<Set<Key>>(new Set(["news", "travel"]));9  return (10    <TagGroup11      aria-label="Categories (controlled)"12      selectedKeys={selected}13      selectionMode="multiple"14      onSelectionChange={setSelected}15    >16      <Label>Categories (controlled)</Label>17      <TagGroup.List>18        <Categories />19      </TagGroup.List>20      <Description>Selected: {selected.size ? [...selected].join(", ") : "None"}</Description>21    </TagGroup>22  );23}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带错误信息

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 with-error-message adaptation (Apache-2.0).3import { useState, type Key } from "react";4import { Tag, TagGroup } from "@lenso/ui";5import { Description, ErrorMessage, Label } from "./text";6const amenities = [7  ["laundry", "Laundry"],8  ["fitness", "Fitness center"],9  ["parking", "Parking"],10  ["pool", "Swimming pool"],11  ["breakfast", "Breakfast"],12];13export function TagGroupWithErrorMessage() {14  const [selected, setSelected] = useState<Set<Key>>(new Set());15  return (16    <TagGroup17      aria-label="Amenities"18      selectedKeys={selected}19      selectionMode="multiple"20      onSelectionChange={setSelected}21      aria-invalid={!selected.size}22    >23      <Label>Amenities</Label>24      <TagGroup.List>25        {amenities.map(([key, name]) => (26          <Tag key={key} itemKey={key!} textValue={name!}>27            {name}28          </Tag>29        ))}30      </TagGroup.List>31      <Description>32        {!selected.size ? "Select at least one category" : `Selected: ${[...selected].join(", ")}`}33      </Description>34      <ErrorMessage>{!selected.size && "Please select at least one category"}</ErrorMessage>35    </TagGroup>36  );37}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带列表数据

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 with-list-data adaptation (Apache-2.0); native controlled collection.3import { useState, type Key } from "react";4import * as stylex from "@stylexjs/stylex";5import { Avatar, EmptyState, Tag, TagGroup } from "@lenso/ui";6import { Description, Label } from "./text";7import { styles } from "./categories";8const initial = ["Fred", "Michael", "Jane", "Alice", "Bob", "Charlie"].map((name, index) => ({9  key: name.toLowerCase(),10  textValue: name,11  color: ["blue", "green", "purple", "red", "orange", "black"][index],12}));13export function TagGroupWithListData() {14  const [items, setItems] = useState(initial);15  const [selected, setSelected] = useState<Set<Key>>(new Set(["fred", "michael"]));16  const avatar = (user: (typeof initial)[number]) => (17    <Avatar xstyle={styles.avatar} size="sm">18      <Avatar.Image19        alt={user.textValue}20        src={`https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/${user.color}.jpg`}21      />22      <Avatar.Fallback>{user.textValue[0]}</Avatar.Fallback>23    </Avatar>24  );25  return (26    <div {...stylex.props(styles.width)}>27      <TagGroup28        aria-label="Team Members"29        selectedKeys={selected}30        selectionMode="multiple"31        onSelectionChange={setSelected}32        onRemove={(keys) => setItems((previous) => previous.filter((user) => !keys.has(user.key)))}33      >34        <Label>Team Members</Label>35        <TagGroup.List>36          {items.length ? (37            items.map((user) => (38              <Tag key={user.key} itemKey={user.key} textValue={user.textValue}>39                {avatar(user)}40                {user.textValue}41              </Tag>42            ))43          ) : (44            <EmptyState>No team members</EmptyState>45          )}46        </TagGroup.List>47        <Description>Select team members for your project</Description>48      </TagGroup>49      {selected.size > 0 && (50        <>51          <p>Selected:</p>52          <div {...stylex.props(styles.selected)}>53            {items54              .filter((user) => selected.has(user.key))55              .map((user) => (56                <div key={user.key} {...stylex.props(styles.selectedUser)}>57                  {avatar(user)}58                  <span>{user.textValue}</span>59                </div>60              ))}61          </div>62        </>63      )}64    </div>65  );66}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带前缀

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 with-prefix adaptation (Apache-2.0).3import * as stylex from "@stylexjs/stylex";4import { Avatar, Tag, TagGroup } from "@lenso/ui";5import { Description, Label } from "./text";6import { Categories, styles } from "./categories";7export function TagGroupWithPrefix() {8  return (9    <div {...stylex.props(styles.stack)}>10      <TagGroup aria-label="With Icons" selectionMode="single">11        <Label>With Icons</Label>12        <TagGroup.List>13          <Categories icons />14        </TagGroup.List>15        <Description>Tags with icons</Description>16      </TagGroup>17      <TagGroup aria-label="With Avatars" selectionMode="single">18        <Label>With Avatars</Label>19        <TagGroup.List>20          {["Fred", "Michael", "Jane"].map((name, index) => (21            <Tag key={name} itemKey={name.toLowerCase()} textValue={name}>22              <Avatar xstyle={styles.avatar}>23                <Avatar.Image24                  alt={name}25                  src={`https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/${["blue", "green", "purple"][index]}.jpg`}26                />27                <Avatar.Fallback>{name[0]}</Avatar.Fallback>28              </Avatar>29              {name}30            </Tag>31          ))}32        </TagGroup.List>33        <Description>Tags with avatars</Description>34      </TagGroup>35    </div>36  );37}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带移除按钮

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 with-remove-button adaptation (Apache-2.0).3import { useState, type Key } from "react";4import * as stylex from "@stylexjs/stylex";5import { Icon } from "@iconify/react";6import { EmptyState, Tag, TagGroup } from "@lenso/ui";7import { Description, Label } from "./text";8import { styles } from "./categories";9function Removable({ custom = false }: { custom?: boolean }) {10  const [items, setItems] = useState(11    custom ? ["React", "Vue", "Angular", "Svelte"] : ["News", "Travel", "Gaming", "Shopping"],12  );13  const remove = (keys: Set<Key>) =>14    setItems((previous) => previous.filter((name) => !keys.has(name.toLowerCase())));15  return (16    <TagGroup17      aria-label={custom ? "Custom Remove Button" : "Default Remove Button"}18      selectionMode="single"19      onRemove={remove}20    >21      <Label>{custom ? "Custom Remove Button" : "Default Remove Button"}</Label>22      <TagGroup.List>23        {items.length ? (24          items.map((name) => (25            <Tag key={name} itemKey={name.toLowerCase()} textValue={name}>26              {custom27                ? ({ allowsRemoving }) => (28                    <>29                      {name}30                      {allowsRemoving && (31                        <Tag.RemoveButton>32                          <Icon icon="gravity-ui:circle-xmark-fill" width={12} aria-hidden="true" />33                        </Tag.RemoveButton>34                      )}35                    </>36                  )37                : name}38            </Tag>39          ))40        ) : (41          <EmptyState>{custom ? "No frameworks found" : "No categories found"}</EmptyState>42        )}43      </TagGroup.List>44      <Description>45        {custom ? "Custom remove button with icon" : "Click the X to remove tags"}46      </Description>47    </TagGroup>48  );49}50export function TagGroupWithRemoveButton() {51  return (52    <div {...stylex.props(styles.stack)}>53      <Removable />54      <Removable custom />55    </div>56  );57}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 render-function adaptation (Apache-2.0).3import { TagGroup } from "@lenso/ui";4import { Categories } from "./categories";5export function RenderFunction() {6  return (7    <TagGroup8      aria-label="Tags"9      render={(props) => <div {...props} data-custom="foo" />}10      selectionMode="single"11    >12      <TagGroup.List>13        <Categories icons prefix="default-" />14      </TagGroup.List>15    </TagGroup>16  );17}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6 custom-styles adaptation (Apache-2.0).3import { TagGroup } from "@lenso/ui";4import { Categories, styles } from "./categories";5export function CustomStyles() {6  return (7    <TagGroup aria-label="Topics" selectionMode="single">8      <TagGroup.List xstyle={styles.list}>9        <Categories icons custom />10      </TagGroup.List>11    </TagGroup>12  );13}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

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

1@layer components {2  .tag-group {3    @apply flex flex-col gap-2;4  }5
6  .tag-group__list {7    @apply flex flex-wrap gap-2;8  }9
10  .tag {11    @apply rounded-full px-3 py-1;12  }13
14  .tag__remove-button {15    @apply ml-1;16  }17}

样式参考

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

CSS 类

TagGroup 组件使用以下 CSS 类（查看源码样式与 tag.css）：

基础类 [!toc]

.tag-group - TagGroup 根容器
.tag-group__list - 标签列表容器
.tag - 标签基础样式
.tag__remove-button - 移除按钮触发器

插槽类 [!toc]

.tag-group [slot="description"] - Description 插槽样式
.tag-group [slot="errorMessage"] - ErrorMessage 插槽样式

尺寸类 [!toc]

.tag--sm - 小尺寸标签
.tag--md - 中尺寸标签（默认）
.tag--lg - 大尺寸标签

变体类 [!toc]

.tag--default - 默认变体
.tag--surface - 带 Surface 背景的变体

状态类 [!toc]

.tag[data-selected="true"] - 选中状态
.tag[data-disabled="true"] - 禁用状态
.tag[data-hovered="true"] - 悬停状态
.tag[data-pressed="true"] - 按下状态
.tag[data-focus-visible="true"] - 聚焦状态（键盘焦点）

交互状态

该组件同时支持 CSS 伪类与 data 属性：

悬停：标签上 :hover 或 [data-hovered="true"]
聚焦：标签上 :focus-visible 或 [data-focus-visible="true"]
按下：标签上 :active 或 [data-pressed="true"]
已选中：标签上 [data-selected="true"] 或 [aria-selected="true"]
禁用：标签上 :disabled 或 [data-disabled="true"]

API 参考

Prop	类型	默认值	描述
`selectionMode`	`"none" \| "single" \| "multiple"`	`"none"`	允许的选择类型。
`selectedKeys`	`Selection`	-	当前选中的 key（受控）。
`defaultSelectedKeys`	`Selection`	-	初始选中的 key（非受控）。
`onSelectionChange`	`(keys: Selection) => void`	-	选中变化时调用的事件处理函数。
`disabledKeys`	`Iterable<Key>`	-	禁用标签的 key。
`isDisabled`	`boolean`	-	是否禁用整个 TagGroup。
`onRemove`	`(keys: Set<Key>) => void`	-	移除标签时调用的事件处理函数。
`size`	`"sm" \| "md" \| "lg"`	`"md"`	组内标签尺寸。
`variant`	`"default" \| "surface"`	`"default"`	标签视觉变体。
`className`	`string`	-	额外的 Tailwind CSS 类。
`children`	`ReactNode \| RenderFunction`	-	TagGroup 内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

TagGroup.List

Prop	类型	默认值	描述
`items`	`Iterable<T>`	-	标签列表要展示的数据项。
`renderEmptyState`	`() => ReactNode`	-	列表为空时的渲染函数。
`className`	`string`	-	额外的 Tailwind CSS 类。
`children`	`ReactNode \| RenderFunction`	-	标签列表内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

Tag

Prop	类型	默认值	描述
`id`	`Key`	-	标签唯一标识。
`textValue`	`string`	-	标签内容的字符串表示，用于无障碍。
`isDisabled`	`boolean`	-	是否禁用该标签。
`className`	`string`	-	额外的 Tailwind CSS 类。
`children`	`ReactNode \| RenderFunction`	-	标签内容或渲染函数。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

提示： size、variant 由父级 TagGroup 继承，无法在单个 Tag 上直接设置。

Tag.RemoveButton

Prop	类型	默认值	描述
`className`	`string`	-	额外的 Tailwind CSS 类。
`children`	`ReactNode`	-	自定义移除按钮内容（默认为关闭图标）。

提示： Tag.RemoveButton 支持类似 SearchField.ClearButton 的定制方式。当为 TagGroup 提供 onRemove 时：

自动渲染：若 Tag 的子节点中未包含自定义 Tag.RemoveButton，会自动渲染默认移除按钮。
自定义按钮：若在 Tag 下提供了自定义 Tag.RemoveButton，将替换自动渲染的按钮。
自定义图标：可向 Tag.RemoveButton 传入自定义子内容（如图标）以改变外观。

示例 — 自动渲染（默认）：

1<TagGroup onRemove={handleRemove}>2  <TagGroup.List>3    <Tag id="news">News</Tag>4    {/* Remove button is automatically rendered */}5  </TagGroup.List>6</TagGroup>

示例 — 自定义 RemoveButton（带图标）：

1<TagGroup onRemove={handleRemove}>2  <TagGroup.List>3    <Tag id="news">4      News5      <Tag.RemoveButton>6        <CustomIcon />7      </Tag.RemoveButton>8    </Tag>9  </TagGroup.List>10</TagGroup>

示例 — 在 render props 中使用自定义 RemoveButton：

1<Tag id="news">2  {(renderProps) => (3    <>4      News5      {!!renderProps.allowsRemoving && (6        <Tag.RemoveButton>7          <CustomIcon />8        </Tag.RemoveButton>9      )}10    </>11  )}12</Tag>

RenderProps

在 TagGroup.List 中使用渲染函数时，会传入以下值：

Prop	类型	描述
`isSelected`	`boolean`	标签是否选中。
`isDisabled`	`boolean`	标签是否禁用。
`isHovered`	`boolean`	标签是否悬停。
`isPressed`	`boolean`	标签是否按下。
`isFocused`	`boolean`	标签是否聚焦。
`isFocusVisible`	`boolean`	标签是否为可见键盘焦点。

TagGroup 标签组

用法

组件结构

示例

尺寸

变体

禁用

选择模式

受控组件

带错误信息

带列表数据

带前缀

带移除按钮

渲染函数

自定义样式

Tailwind CSS

全局 CSS

样式参考

CSS 类

基础类 [!toc]

插槽类 [!toc]

尺寸类 [!toc]

变体类 [!toc]

状态类 [!toc]

交互状态

API 参考

TagGroup

TagGroup.List

Tag

Tag.RemoveButton

RenderProps

相关组件