Tag group usage guidelines

Usage guidelines API

Tag group is a container component that organizes and manages collections of tags. Tags are concise, descriptive labels that help categorize and summarize information. Use tag groups when you need to display, select, or manage sets of related tags in your interface.

When to use

For data that is added or generated by the users
To categorize information (e.g., surface, color)
To filter content based on specific attributes
To display associated metadata

When not to use

Tags are not a replacement for action buttons or links between pages.
For system status, use badges instead.
Avoid excessive tagging - too many tags can overwhelm users. Instead, organize related tags into separate tag groups to improve clarity and usability.

Badges vs. tags
Badges and tags may look similar, but they serve different purposes:

Badges are non-interactive, purely informational, and can be used on their own. They are a better fit for presenting predefined content.
Tags are usually interactive, and can only be used as part of a group. They are a better fit for presenting user-generated content.

import { Tag, TagGroup } from '@cimpress-ui/react';

export default function Example() {
  return (
    <TagGroup label="Favorite fruits">
      <Tag>Apple</Tag>
      <Tag>Banana</Tag>
      <Tag>Orange</Tag>
      <Tag>Mango</Tag>
      <Tag>Strawberry</Tag>
    </TagGroup>
  );
}

The default tag group displays a collection of static, non-interactive tags. This is useful for showing metadata, categories, or other read-only information. Each tag in the group can include an optional icon to provide additional visual context.

Removable

Preview
Code

import { Stack, Tag, TagGroup, Text } from '@cimpress-ui/react';
import { IconInfoCircle } from '@cimpress-ui/react/icons';
import { useState } from 'react';

export default function Example() {
  const [tags, setTags] = useState([
    { id: 'apple', label: 'Apple' },
    { id: 'banana', label: 'Banana' },
    { id: 'orange', label: 'Orange' },
    { id: 'mango', label: 'Mango' },
    { id: 'strawberry', label: 'Strawberry' },
  ]);

  return (
    <TagGroup
      label="Favorite fruits"
      items={tags}
      onRemove={(keys) => {
        setTags(tags.filter((t) => !keys.has(t.id)));
      }}
      renderEmptyState={() => (
        <Stack gap={8} direction="horizontal" align="center">
          <IconInfoCircle size={24} tone="base" />
          <Text as="p" variant="medium" tone="base">
            No tags added
          </Text>
        </Stack>
      )}
    >
      {(item) => <Tag>{item.label}</Tag>}
    </TagGroup>
  );
}

Removable tags are used to show applied filters, selections, or labels that users can remove individually. These tags often appear as part of multi-select filters, search chips, or input fields.

Selectable

Preview
Code

import { Tag, TagGroup, type Selection } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Example() {
  const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());
  const tags = [
    { id: 'apple', label: 'Apple' },
    { id: 'banana', label: 'Banana' },
    { id: 'orange', label: 'Orange' },
    { id: 'mango', label: 'Mango' },
    { id: 'strawberry', label: 'Strawberry' },
  ];

  return (
    <TagGroup
      label="Favorite fruits"
      selectionMode="multiple"
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}
      items={tags}
    >
      {(item) => <Tag>{item.label}</Tag>}
    </TagGroup>
  );
}

A selectable tag is an interactive UI component that represents a category, attribute, or filter that users can select to refine a selection.

Formatting and layout

Placement

Tag groups are usually part of a section or stack and should wrap and fill the available space. Tags in a group should flow horizontally, never vertically.

Content that is too wide can be difficult to scan, which negatively impacts readability. Avoid using a horizontal alignment for tag groups if the content will exceed the width of its container.

Tag consistency

Maintain visual consistency by using tags of the same size and styling within a group. Mixing tags with and without icons can create visual imbalance.

Don't

Spacing

Tags within a group have 8px of spacing between them both horizontally and vertically.
A tag group should have 16px of spacing or the default form gap between it and other components.

Content writing

A tag group’s contents should belong to the same category.

The text within tags should be simple and easy to understand, providing only necessary clarity or context. If additional text is required, explore alternative text placement or other components.

Don't

Empty states should guide users with clear, relevant language aligned to the overall user experience. Empty states can either be informative, such as “No tags added,” or action-oriented, such as “Add tags to filter.” The designer should decide which framing is best suited to their use case.

Behaviors

Structure

The tag’s height depends on the size of the tag (medium, large), while its width adjusts dynamically to fit the label’s width. Single tags cannot extend beyond a single line.

Selecting a tag

A user can choose one or more tags from a tag group, this is useful for filtering data or for quickly adding a set of predefined attributes.

Removing a tag

Users can delete individual tags from tag groups that support removable tags. To delete a tag, the user can either press the Delete or Backspace key, or click the “X” icon.