Tag

v1.1.2

Documentation Under Review

The Tag component provides a compact, visually distinct label for categorizing content, displaying status, or organizing information. The product variant features smaller sizing optimized for dense layouts and supports custom styling with CVA for branded applications.

Installation

npm install @pmi/catalyst-tag

Usage

import { TagRoot, TagSlot, TagButton } from '@pmi/catalyst-tag';
import { TokenIcon, CloseIcon } from '@pmi/catalyst-icons';

<TagRoot>
  <TagSlot>
    <TokenIcon />
  </TagSlot>
  Tag Text
</TagRoot>

Composition Pattern

The Tag component uses a composite pattern with three parts:

• TagRoot: Container that manages tag state and appearance
• TagSlot: Flexible slot for icons or custom content
• TagButton: Optional close/remove button

This pattern allows maximum flexibility while maintaining consistent styling.

Examples

Basic Tag

A simple tag with an icon and text.

Sizes

Tags are available in three sizes optimized for product UIs: small, medium, and large.

Danger State

Use the danger state to indicate warnings, errors, or destructive actions.

Disabled State

Disabled tags have reduced opacity and are not interactive.

With Remove Button

Add a close button for removable tags.

AsChild Pattern

Use the asChild prop to compose tags with other components like buttons.

Interactive States

Tags support hover and focus states for interactive elements.

Custom Styling

Apply custom brand colors and styling using CVA for product-specific designs.

TagRoot

The root container component that manages tag state and appearance.

TagSlot

A flexible slot for icons or custom content.

TagButton

An optional button for close/remove functionality.

Size Reference

Product variant uses smaller sizes optimized for dense UI layouts:

Accessibility

The Tag component follows accessibility best practices:

• Keyboard Navigation: Tags are focusable and navigable with Tab key
• Focus Management: tabIndex automatically managed (set to -1 when disabled)
• Focus Indicators: Visible outline on focus (2px with offset)
• Button Accessibility: TagButton has proper focus ring and keyboard support
• ARIA Attributes: Semantic HTML structure for screen readers
• Disabled State: tabIndex={-1} prevents focus on disabled tags

Best Practices

1. Focus Management: Set tabIndex={-1} on TagRoot when using TagButton to prevent double focus. TagButton will receive focus naturally as a button element
2. Icon Size: Match icon size to tag size (use sm icons for all product tag sizes)
3. Remove Functionality: Provide clear visual feedback when tags are removable
4. Danger State: Use sparingly for warnings, errors, or destructive actions
5. Group Related Tags: Use consistent sizing and spacing in tag collections
6. Custom Styling: When using CVA customization, maintain sufficient contrast ratios
7. Dense Layouts: Product sizing is optimized for data-heavy interfaces
8. Text Length: Keep tag text concise (1-3 words optimal)
9. Interactive Elements: TagButton automatically receives focus when TagRoot has tabIndex=-1

Related Components

• Badge - Numeric indicators and status badges
• Button - Interactive buttons with similar styling
• Chip - Alternative compact label component