TagGroup

Import

import { TagGroup } from '@heroui/react';

Usage

Anatomy

import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';

export default () => (
  <TagGroup>
    <Label />
    <TagGroup.List>
      <Tag>
        <Tag.RemoveButton />
      </Tag>
    </TagGroup.List>
    <Description />
    <ErrorMessage />
  </TagGroup>
)

Sizes

Variants

Disabled

Selection Modes

Controlled

With Error Message

With Prefix

With Remove Button

With List Data

Custom Render Function

Styling

Passing Tailwind CSS classes

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

function CustomTagGroup() {
  return (
    <TagGroup className="w-full">
      <Label>Categories</Label>
      <TagGroup.List className="gap-2">
        <Tag className="rounded-lg px-4 py-2 font-bold">
          Custom Styled
        </Tag>
      </TagGroup.List>
    </TagGroup>
  );
}

Customizing the component classes

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

@layer components {
  .tag-group {
    @apply flex flex-col gap-2;
  }

  .tag-group__list {
    @apply flex flex-wrap gap-2;
  }

  .tag {
    @apply rounded-full px-3 py-1;
  }

  .tag__remove-button {
    @apply ml-1;
  }
}

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

• .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

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

Size Classes

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

Variant Classes

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

State Classes

• .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

TagGroup Props

TagGroup.List Props

Tag Props

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

Tag.RemoveButton Props

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):

<TagGroup onRemove={handleRemove}>
  <TagGroup.List>
    <Tag id="news">News</Tag>
    {/* Remove button is automatically rendered */}
  </TagGroup.List>
</TagGroup>

Example - Custom RemoveButton with icon:

<TagGroup onRemove={handleRemove}>
  <TagGroup.List>
    <Tag id="news">
      News
      <Tag.RemoveButton>
        <CustomIcon />
      </Tag.RemoveButton>
    </Tag>
  </TagGroup.List>
</TagGroup>

Example - Custom RemoveButton in render props:

<Tag id="news">
  {(renderProps) => (
    <>
      News
      {!!renderProps.allowsRemoving && (
        <Tag.RemoveButton>
          <CustomIcon />
        </Tag.RemoveButton>
      )}
    </>
  )}
</Tag>

RenderProps

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