TagGroup

Tags allow users to categorize content. They can represent keywords or people, and are grouped to describe an item or a search request.

Ice cream flavors

Chocolate

Mint

Strawberry

Vanilla

Chocolate Chip Cookie Dough

Rocky Road

Butter Pecan

Neapolitan

Salted Caramel

Mint Chocolate Chip

Tonight Dough

Lemon Cookie

Cookies and Cream

Phish Food

Peanut Butter Cup

Coffee

Pistachio

Cherry

Chocolate

Mint

Strawberry

Vanilla

Chocolate Chip Cookie Dough

Rocky Road

Butter Pecan

Neapolitan

Salted Caramel

Mint Chocolate Chip

Tonight Dough

Lemon Cookie

Cookies and Cream

Phish Food

Peanut Butter Cup

Coffee

Pistachio

Cherry

label

selectionMode

size

labelPosition

maxRows

description

contextualHelp

isEmphasized

import {TagGroup, Tag} from '@react-spectrum/s2';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

<TagGroup
  label="Ice cream flavors"
  selectionMode="multiple"
  maxRows={2}>
  <Tag>Chocolate</Tag>
  <Tag>Mint</Tag>
  <Tag>Strawberry</Tag>
  <Tag>Vanilla</Tag>
  <Tag>Chocolate Chip Cookie Dough</Tag>
  <Tag>Rocky Road</Tag>
  <Tag>Butter Pecan</Tag>
  <Tag>Neapolitan</Tag>
  <Tag>Salted Caramel</Tag>
  <Tag>Mint Chocolate Chip</Tag>
  <Tag>Tonight Dough</Tag>
  <Tag>Lemon Cookie</Tag>
  <Tag>Cookies and Cream</Tag>
  <Tag>Phish Food</Tag>
  <Tag>Peanut Butter Cup</Tag>
  <Tag>Coffee</Tag>
  <Tag>Pistachio</Tag>
  <Tag>Cherry</Tag>
</TagGroup>

Content

TagGroup follows the Collection Components API, accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the items prop, and a function to render the children. Items can be removed via the onRemove event.

Photo categories

Landscape

Portrait

Night

Dual

Golden Hour

import {TagGroup, Tag, TextField, Button} from '@react-spectrum/s2';
import {useListData} from 'react-stately';
import {useState} from 'react';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

function PhotoCategories() {
  let list = useListData({
    initialItems: [
      {id: 1, name: 'Landscape'},
      {id: 2, name: 'Portrait'},
      {id: 3, name: 'Night'},
      {id: 4, name: 'Dual'},
      {id: 5, name: 'Golden Hour'}
    ]
  });

  return (
    <TagGroup
      label="Photo categories"
      styles={style({width: 320})}
      items={list.items}
      onRemove={(keys) => list.remove(...keys)}>
      {(item) => <Tag>{item.name}</Tag>}
    </TagGroup>
  );
}

Slots

Tag supports icons, avatars, or images, and text as children.

Media types

Text

Photos

Videos

Illustration

import {TagGroup, Tag, Text} from '@react-spectrum/s2';
import FileText from '@react-spectrum/s2/icons/FileText';
import Camera from '@react-spectrum/s2/icons/Camera';
import Filmstrip from '@react-spectrum/s2/icons/Filmstrip';
import VectorDraw from '@react-spectrum/s2/icons/VectorDraw';

<TagGroup label="Media types">
  <Tag textValue="Text">
    <FileText />
    <Text>Text</Text>
  </Tag>
  <Tag textValue="Photos">
    <Camera />
    <Text>Photos</Text>
  </Tag>
  <Tag textValue="Videos">
    <Filmstrip />
    <Text>Videos</Text>
  </Tag>
  <Tag textValue="Illustration">
    <VectorDraw />
    <Text>Illustration</Text>
  </Tag>
</TagGroup>

Links

Use the href prop on a <Tag> to create a link. See the client side routing guide to learn how to integrate with your framework.

Photo categories

Landscape

Portrait

Macro

Night

Dual

Golden Hour

import {TagGroup, Tag} from '@react-spectrum/s2';

<TagGroup label="Photo categories">
  <Tag href="https://en.wikipedia.org/wiki/Landscape_photography" target="_blank">Landscape</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Portrait_photography" target="_blank">Portrait</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Macro_photography" target="_blank">Macro</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Night_photography" target="_blank">Night</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Dualphotography" target="_blank">Dual</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Golden_hour_(photography)" target="_blank">Golden Hour</Tag>
</TagGroup>

Empty state

Use renderEmptyState to render placeholder content when the TagGroup is empty.

Photo categories

No categories. Click here to add some.

import {TagGroup, Link} from '@react-spectrum/s2';

<TagGroup
  label="Photo categories"
  renderEmptyState={() => (
    <>No categories. <Link href="https://react-spectrum.adobe.com/">Click here</Link> to add some.</>
  )}>
  {[]}
</TagGroup>

Selection

Use the selectionMode prop to enable single or multiple selection. The selected items can be controlled via the selectedKeys prop, matching the id prop of the items. Items can be disabled with the isDisabled prop. See the selection guide for more details.

Amenities

Laundry

Fitness center

Parking

Swimming pool

Breakfast

Current selection:

selectionMode

selectionBehavior

disallowEmptySelection

import {TagGroup, Tag} from '@react-spectrum/s2';
import {useState} from 'react';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

function Example(props) {
  let [selected, setSelected] = useState<Selection>(new Set());

  return (
    <div>
      <TagGroup
        {...props}
        label="Amenities"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Tag id="laundry">Laundry</Tag>
        <Tag id="fitness">Fitness center</Tag>
        <Tag id="parking" isDisabled>Parking</Tag>
        <Tag id="pool">Swimming pool</Tag>
        <Tag id="breakfast">Breakfast</Tag>
      </TagGroup>
      <p>Current selection: {selected === 'all' ? 'all' : [...selected].join(', ')}</p>
    </div>
  );
}

Group actions

Use the groupActionLabel and onGroupAction props to add an action button at the end of the tags.

Interests

News

Travel

Gaming

Shopping

import {TagGroup, Tag} from '@react-spectrum/s2';

<TagGroup
  label="Interests"
  groupActionLabel="Clear"
  onGroupAction={() => alert('Clear')}>
  <Tag>News</Tag>
  <Tag>Travel</Tag>
  <Tag>Gaming</Tag>
  <Tag>Shopping</Tag>
</TagGroup>

API

<TagGroup>
  <Tag />
</TagGroup>

Tags allow users to categorize content. They can represent keywords or people, and are grouped to describe an item or a search request.

Name	Type	Default
`size`	`'S' \| 'M' \| 'L'`	Default: `'M'`
The size of the tag group.
`isEmphasized`	`boolean`	Default: —
Whether the tags are displayed in an emphasized style.
`maxRows`	`number`	Default: —
Limit the number of rows initially shown. This will render a button that allows the user to expand to show all tags.
`groupActionLabel`	`string`	Default: —
The label to display on the action button.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

`children`	`ReactNode \| (item: T) => ReactNode`	Default: —
The contents of the collection.
`items`	`Iterable<T>`	Default: —
Item objects in the collection.
`renderEmptyState`	`() => ReactNode`	Default: —
Provides content to display when there are no items in the tag group.

`selectionMode`	`SelectionMode`	Default: —
The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	Default: —
How multiple selection should behave in the collection.
`selectedKeys`	`'all' \| Iterable<Key>`	Default: —
The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	Default: —
The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`(keys: Selection) => void`	Default: —
Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	Default: —
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`	Default: —
Whether the collection allows empty selection.
`shouldSelectOnPressUp`	`boolean`	Default: —
Whether selection should occur on press up instead of press down.
`escapeKeyBehavior`	`'clearSelection' \| 'none'`	Default: `'clearSelection'`
Whether pressing the escape key should clear selection in the TagGroup or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.

Tag

An individual Tag for TagGroups.

Name	Type
`children`	`ReactNode`
The children of the tag.
`id`	`Key`
A unique id for the tag.
`textValue`	`string`
A string representation of the tags's contents, used for accessibility. Required if children is not a plain text string.
`isDisabled`	`boolean`
Whether the tag is disabled.