Tag group API

Import

Cimpress UI exports two tag-related components:

TagGroup: container component that groups related tags together, providing a label, description, error handling, and selection and removal.
Tag: component to display a tag within a tag group, optionally with an icon.

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

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

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

export default function Demo() {
  const [selectedKeys, setSelectedKeys] = useState<Selection>(() => new Set(['apple']));

  return (
    <Stack gap={32}>
      <TagGroup
        label="Favorite fruits (controlled)"
        selectionMode="multiple"
        selectedKeys={selectedKeys}
        onSelectionChange={setSelectedKeys}
      >
        <Tag id="apple">Apple</Tag>
        <Tag id="banana">Banana</Tag>
        <Tag id="cherry">Cherry</Tag>
      </TagGroup>

      <TagGroup label="Favorite fruits (uncontrolled)" selectionMode="multiple" defaultSelectedKeys={['apple']}>
        <Tag id="apple">Apple</Tag>
        <Tag id="banana">Banana</Tag>
        <Tag id="cherry">Cherry</Tag>
      </TagGroup>
    </Stack>
  );
}

Accessibility notes

TagGroup requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

TagGroup is a single tab stop within the page’s tab order. Use the Tab key to navigate to the group, and the arrow keys to navigate between tags within the group. Use the Backspace or Delete key to remove tags from the group.

Collections

TagGroup is a collection component. See our collection components guide to learn how to work with collections.

API reference

Displays a group of tags. Allows for selecting or removing tags.

See tag group usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

TagGroupProps<T extends CollectionItem = CollectionItem>

isRequired Section titled “ isRequired ” boolean: Whether the tag group is required.
error Section titled “ error ” string: The error message to display.
size Section titled “ size ” 'medium' | 'large': The size of the tags.
renderEmptyState Section titled “ renderEmptyState ” () => ReactNode: Provides content to display when there are no tags in the group.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
label Section titled “ label ” string: The content to display as the label.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
description Section titled “ description ” string: A description for the field. Provides a hint such as specific requirements for what to choose.
onRemove Section titled “ onRemove ” (keys: Set<Key>) => void: Handler that is called when a user deletes a tag.
items Section titled “ items ” Iterable<T, any, any>: Item objects in the collection.
disabledKeys Section titled “ disabledKeys ” Iterable<Key, any, any>: The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
selectionMode Section titled “ selectionMode ” SelectionMode: The type of selection that is allowed in the collection.
selectedKeys Section titled “ selectedKeys ” 'all' | (Iterable<Key, any, any>): The currently selected keys in the collection (controlled).
defaultSelectedKeys Section titled “ defaultSelectedKeys ” 'all' | (Iterable<Key, any, any>): The initial selected keys in the collection (uncontrolled).
onSelectionChange Section titled “ onSelectionChange ” (keys: Selection) => void: Handler that is called when the selection changes.
children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Tag group API

Import

Controlled/uncontrolled usage

Accessibility notes

Collections

API reference

Tag

ref

children *

iconStart

data-cim-style-root

UNSAFE_className

UNSAFE_style

id

isDisabled

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

Tag group API

Import

Controlled/uncontrolled usage

Accessibility notes

Collections

API reference

TagGroup

ref

isRequired

error

size

renderEmptyState

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

label

aria-label

aria-labelledby

aria-describedby

aria-details

description

onRemove

items

disabledKeys

selectionMode

selectedKeys

defaultSelectedKeys

onSelectionChange

children

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

Tag

ref

children *

iconStart

data-cim-style-root

UNSAFE_className

UNSAFE_style

id

isDisabled

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft