TagGroup

A focusable list of tags with support for keyboard navigation, selection, and removal

Usage

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.

Anatomy

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)

Examples

Sizes

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.

Variants

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.

Disabled

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.

Selection Modes

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.

Controlled

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.

With Error Message

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.

With List Data

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.

With Prefix

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.

With Remove Button

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.

Render Function

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.

Customization

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.

Global CSS

To customize the TagGroup component classes, you can use the @layer components directive. Learn more.

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}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The TagGroup component uses these CSS classes (View source styles and tag.css):

Base Classes [!toc]

.tag-group - Base tag group container
.tag-group__list - Container for the list of tags
.tag - Base tag styles
.tag__remove-button - Remove button trigger

Slot Classes [!toc]

.tag-group [slot="description"] - Description slot styles
.tag-group [slot="errorMessage"] - ErrorMessage slot styles

Size Classes [!toc]

.tag--sm - Small size tag
.tag--md - Medium size tag (default)
.tag--lg - Large size tag

Variant Classes [!toc]

.tag--default - Default variant
.tag--surface - Surface variant with surface background

State Classes [!toc]

.tag[data-selected="true"] - Selected tag state
.tag[data-disabled="true"] - Disabled tag state
.tag[data-hovered="true"] - Hovered tag state
.tag[data-pressed="true"] - Pressed tag state
.tag[data-focus-visible="true"] - Focused tag state (keyboard focus)

Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

Hover: :hover or [data-hovered="true"] on tag
Focus: :focus-visible or [data-focus-visible="true"] on tag
Pressed: :active or [data-pressed="true"] on tag
Selected: [data-selected="true"] or [aria-selected="true"] on tag
Disabled: :disabled or [data-disabled="true"] on tag

API Reference

Prop	Type	Default	Description
`selectionMode`	`"none" \| "single" \| "multiple"`	`"none"`	The type of selection that is allowed
`selectedKeys`	`Selection`	-	The currently selected keys (controlled)
`defaultSelectedKeys`	`Selection`	-	The initial selected keys (uncontrolled)
`onSelectionChange`	`(keys: Selection) => void`	-	Handler called when the selection changes
`disabledKeys`	`Iterable<Key>`	-	Keys of disabled tags
`isDisabled`	`boolean`	-	Whether the tag group is disabled
`onRemove`	`(keys: Set<Key>) => void`	-	Handler called when tags are removed
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Size of the tags in the group
`variant`	`"default" \| "surface"`	`"default"`	Visual variant of the tags
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode \| RenderFunction`	-	TagGroup content or render function
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>`	-	Overrides the default DOM element with a custom render function.

TagGroup.List

Prop	Type	Default	Description
`items`	`Iterable<T>`	-	The items to display in the tag list
`renderEmptyState`	`() => ReactNode`	-	Function to render when the list is empty
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode \| RenderFunction`	-	TagList content or render function
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>`	-	Overrides the default DOM element with a custom render function.

Tag

Prop	Type	Default	Description
`id`	`Key`	-	The unique identifier for the tag
`textValue`	`string`	-	A string representation of the tag's content, used for accessibility
`isDisabled`	`boolean`	-	Whether the tag is disabled
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode \| RenderFunction`	-	Tag content or render function
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagRenderProps>`	-	Overrides the default DOM element with a custom render function.

Note: size, variant are inherited from the parent TagGroup component and cannot be set directly on individual Tag components.

Tag.RemoveButton

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode`	-	Custom remove button content (defaults to close icon)

Note: The Tag.RemoveButton component supports customization similar to SearchField.ClearButton. When onRemove is provided to TagGroup:

Auto-rendering: If no custom Tag.RemoveButton is included in the Tag children, a default remove button is automatically rendered.
Custom button: If a custom Tag.RemoveButton is provided as a child of Tag, it will be used instead of the auto-rendered button.
Custom icon: You can pass custom content (like icons) to Tag.RemoveButton children to customize the appearance.

Example - Auto-rendered (default):

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

Example - Custom RemoveButton with icon:

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>

Example - Custom RemoveButton in render props:

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

Render Props

When using render functions with TagGroup.List, these values are provided:

Prop	Type	Description
`isSelected`	`boolean`	Whether the tag is selected
`isDisabled`	`boolean`	Whether the tag is disabled
`isHovered`	`boolean`	Whether the tag is hovered
`isPressed`	`boolean`	Whether the tag is pressed
`isFocused`	`boolean`	Whether the tag is focused
`isFocusVisible`	`boolean`	Whether the tag has keyboard focus

Label

Renders an accessible label associated with form controls

Description

Provides supplementary text for form fields and other components

ErrorMessage

A low-level error message component for displaying errors

TagGroup

Usage

Anatomy

Examples

Sizes

Variants

Disabled

Selection Modes

Controlled

With Error Message

With List Data

With Prefix

With Remove Button

Render Function

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Slot Classes [!toc]

Size Classes [!toc]

Variant Classes [!toc]

State Classes [!toc]

Interactive States

API Reference

TagGroup

TagGroup.List

Tag

Tag.RemoveButton

Render Props

Related Components