TagGroup

A collection of tags for labeling, categorizing, or filtering content.

Usage#

import { TagGroup, Tag } from '@backstage/ui';

<TagGroup>
  <Tag>Tag 1</Tag>
  <Tag>Tag 2</Tag>
</TagGroup>

API reference#

Container for a collection of tags.

Prop	Type	Default	Description
items	Iterable<T>	-	Item objects in the collection.
renderEmptyState	() => ReactNode	-	Content to display when the collection is empty.
selectionMode	nonesinglemultiple	-	The type of selection allowed.
selectedKeys	allIterable<Key>	-	The currently selected keys (controlled).
defaultSelectedKeys	allIterable<Key>	-	The initial selected keys (uncontrolled).
disabledKeys	Iterable<Key>	-	Keys of tags that should be disabled.
onRemove	(keys: Set<Key>) => void	-	Handler called when a tag is removed.
onSelectionChange	(keys: Selection) => void	-	Handler called when the selection changes.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria TagGroup props.

Tag#

Individual tag item within a group.

Prop	Type	Default	Description
id	string	-	Unique identifier for the tag.
textValue	string	-	Text value for accessibility. Derived from children if string.
href	string	-	URL to navigate to when the tag is clicked.
icon	ReactNode	-	Icon displayed before the tag text.
size	smallmedium	small	Visual size of the tag. Use small for inline or dense layouts, medium for standalone tags.
isDisabled	boolean	-	Whether the tag is disabled.
noTrack	boolean	-	Suppresses the automatic analytics click event, e.g. if you already have custom tracking.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria Tag props.

Examples#

With links#

<TagGroup>
  <Tag href="/items/banana">Banana</Tag>
  <Tag href="/items/apple">Apple</Tag>
  <Tag href="/items/orange">Orange</Tag>
</TagGroup>

With icons#

<TagGroup>
  <Tag icon={<RiBugLine />}>Banana</Tag>
  <Tag icon={<RiAccountCircleLine />}>Apple</Tag>
  <Tag icon={<RiEyeLine />}>Orange</Tag>
  <Tag icon={<RiHeartLine />}>Pear</Tag>
</TagGroup>

Sizes#

<Flex direction="column">
  <TagGroup>
    <Tag size="small" icon={<RiBugLine />}>Banana</Tag>
    <Tag size="small" icon={<RiAccountCircleLine />}>Apple</Tag>
  </TagGroup>
  <TagGroup>
    <Tag size="medium" icon={<RiBugLine />}>Banana</Tag>
    <Tag size="medium" icon={<RiAccountCircleLine />}>Apple</Tag>
  </TagGroup>
</Flex>

Removable#

const list = useListData({
  initialItems: [
    { id: 'banana', name: 'Banana' },
    { id: 'apple', name: 'Apple' },
    { id: 'orange', name: 'Orange' },
  ],
});

<TagGroup
  items={list.items}
  onRemove={keys => list.remove(...keys)}
>
  {item => <Tag>{item.name}</Tag>}
</TagGroup>

Disabled#

<TagGroup>
  <Tag>Banana</Tag>
  <Tag isDisabled>Apple</Tag>
  <Tag isDisabled>Orange</Tag>
  <Tag>Pear</Tag>
</TagGroup>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-TagGroup
bui-TagList

Changelog#

Version 0.13.0#

Breaking Changes

Tag Group Breaking Centralized client-side routing in BUIProvider. Components like Link, ButtonLink, Tabs, Menu, TagGroup, and Table now require a BUIProvider rendered inside a React Router context for client-side navigation to work. #33267

Migration Guide:

This change requires updating @backstage/plugin-app and @backstage/core-app-api alongside @backstage/ui. If you only upgrade @backstage/ui, BUI components will fall back to full-page navigation.

If you cannot upgrade all packages together, or if you have a custom app shell, add a BUIProvider inside your Router:
```
+ import { BUIProvider } from '@backstage/ui';

  <BrowserRouter>
+   <BUIProvider>
      <AppContent />
+   </BUIProvider>
  </BrowserRouter>
```

Changes

Tag Added analytics capabilities to the component library. Components with navigation behavior (Link, ButtonLink, Tab, MenuItem, Tag, Row) now fire analytics events on click when a BUIProvider is present.

New exports: BUIProvider, useAnalytics, getNodeText, and associated types (AnalyticsTracker, UseAnalyticsFn, BUIProviderProps, AnalyticsEventAttributes).

Components with analytics support now accept a noTrack prop to suppress event firing. #33150
Tag Group Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers. #33050

Version 0.12.0#

Changes

Tag Allow ref as a prop on the Tag component #32742
Tag Group Tag Fixed client-side navigation for container components by wrapping the container (not individual items) in RouterProvider. Components now conditionally provide routing context only when children have internal links, removing the Router context requirement when not needed. This also removes the need to wrap these components in MemoryRouter during tests when they are not using the href prop.

Additionally, when multiple tabs match the current URL via prefix matching, the tab with the most specific path (highest segment count) is now selected. For example, with URL /catalog/users/john, a tab with path /catalog/users is now selected over a tab with path /catalog. #32373