Tag

A tag is a user-generated keyword associated with certain items to categorize them and make them easily discoverable.

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return (
    <TagContainer>
      <Tag>Tag 1</Tag>
      <Tag onRemove={() => {}}>Tag 2</Tag>
      <Tag onRemove={() => {}}>Tag 3</Tag>
    </TagContainer>
  );
};

Tags are user-generated keywords used to label, categorize, or organize items and files. A group of multiple tags is a standard way of labeling an item to make it easily discoverable by peers who may not know the exact title of said item. A single tag may be mapped to more than one project at once if these projects fit in similar categories. Tags may also be used as a way to filter out content; in that context, the tags are pre-existing, and users select tags that fit their search to narrow down the results.

Usage

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return <Tag onRemove={() => {}}>Tag 1</Tag>;
};

Basic tags

Tags in the basic state are static and cannot be removed or edited by the user. No new tags can be added through this state either. This state is commonly seen in tile metadata.

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return (
    <TagContainer>
      <Tag variant='basic'>Tag 1</Tag>
      <Tag variant='basic'>Tag 2</Tag>
    </TagContainer>
  );
};

Props

Prop Description Default
children
Text inside the tag.
ReactNode
onClick
Callback invoked when the tag is clicked.
When this prop is passed, the tag will be rendered as a button.
MouseEventHandler<Element>
onRemove
Callback function that handles click on the remove ("❌") button. If not passed, the remove button will not be shown.
If both onClick and onRemove are passed, then the tag label (rather than the tag itself) will be rendered as a button, to avoid invalid markup (nested buttons).
MouseEventHandler<Element>
removeButtonProps
Props for customizing the remove ("❌") button.
Omit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & { ...; }
variant
Variant of tag. Basic tags don't have an outline.
"default" | "basic"
 'default'
labelProps
Props for customizing the label.
Only relevant for the 'default' Tag.
Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: Ref<...>; }
as
"symbol" | "object" | "span" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 159 more ... | FunctionComponent<...>

Usage guidelines

  • Tags are meant to be used for display purposes. While interactivity is possible, it is not the primary use case.
  • Use basic tags when you need to make tags read-only.

Accessibility

When the onClick prop is passed to Tag, it is automatically rendered as a <button> element. This gives the tag proper semantics and makes it keyboard interactable.

When the onRemove prop is passed to Tag, a remove button is rendered inside the tag. This button has an aria-label set to "Delete tag", which can be customized using the removeButtonProps prop.

If both onClick and onRemove props are passed, then the tag label (rather than the tag itself) will be rendered as a button, to avoid invalid markup (button nested inside another button). This is achieved using the LinkAction component.

Tag container

Tag containers may be used to group tags, depending on the page layout and usage.

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return (
    <TagContainer background='filled'>
      <Tag onRemove={() => {}}>Tag 1</Tag>
      <Tag onRemove={() => {}}>Tag 2</Tag>
      <Tag onRemove={() => {}}>Tag 3</Tag>
      <Tag onRemove={() => {}}>Tag 4</Tag>
    </TagContainer>
  );
};

Wrapping

The wrapping container wraps tags around to the following line when the maximum width is reached on the previous line. This allows display of the full tags without label truncation.

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return (
    <TagContainer background='filled' className='demo-container'>
      <Tag onRemove={() => {}}>Tag 1</Tag>
      <Tag onRemove={() => {}}>Tag 2</Tag>
      <Tag onRemove={() => {}}>Tag 3</Tag>
      <Tag onRemove={() => {}}>Medium tag 4</Tag>
      <Tag onRemove={() => {}}>Very long tag 5</Tag>
      <Tag onRemove={() => {}}>Tag 6</Tag>
      <Tag onRemove={() => {}}>Tag 7</Tag>
      <Tag onRemove={() => {}}>Long tag 8</Tag>
      <Tag onRemove={() => {}}>Tag 9</Tag>
    </TagContainer>
  );
};

Truncating

The truncating container has fixed height, so it only displays tags that fit on a single line, and truncates tags that exceeds the maximum width. It uses ellipsis (…) to inform the user that there are hidden extra tags beyond what is currently shown.

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return (
    <TagContainer
      overflow='truncate'
      background='filled'
      className='demo-container'
    >
      <Tag onRemove={() => {}}>Tag 1</Tag>
      <Tag onRemove={() => {}}>Tag 2</Tag>
      <Tag onRemove={() => {}}>Tag 3</Tag>
      <Tag onRemove={() => {}}>Medium tag 4</Tag>
      <Tag onRemove={() => {}}>Very long tag 5</Tag>
      <Tag onRemove={() => {}}>Tag 6</Tag>
      <Tag onRemove={() => {}}>Tag 7</Tag>
      <Tag onRemove={() => {}}>Long tag 8</Tag>
      <Tag onRemove={() => {}}>Tag 9</Tag>
    </TagContainer>
  );
};

Scrollable

The scrollable container is much like the truncating container, except it allows the user to horizontally scroll to reveal the tags that go beyond the maximum width. The tag that extends past the width is cut off, to hint at the scrolling possibility.

 
import * as React from 'react';
import { TagContainer, Tag } from '@itwin/itwinui-react';

export default () => {
  return (
    <TagContainer
      overflow='scroll'
      background='filled'
      className='demo-container'
    >
      <Tag onRemove={() => {}}>Tag 1</Tag>
      <Tag onRemove={() => {}}>Tag 2</Tag>
      <Tag onRemove={() => {}}>Tag 3</Tag>
      <Tag onRemove={() => {}}>Medium tag 4</Tag>
      <Tag onRemove={() => {}}>Very long tag 5</Tag>
      <Tag onRemove={() => {}}>Tag 6</Tag>
      <Tag onRemove={() => {}}>Tag 7</Tag>
      <Tag onRemove={() => {}}>Long tag 8</Tag>
      <Tag onRemove={() => {}}>Tag 9</Tag>
    </TagContainer>
  );
};

Props

Prop Description Default
children
Tags inside the container.
ReactNode
overflow
Overflow solution to the tag container. Set max-width to have scroll or truncated tags.
"truncate" | "scroll"
background
Use background to have tags standout in your layout. Container gets colored background and some spacing applied.
"none" | "filled"
 'none'
as
"symbol" | "object" | "div" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | "canvas" | ... 158 more ... | FunctionComponent<...>

Usage guidelines

  • Wrapping tag containers are ideal for layouts with plenty of vertical space, in situations where seeing all the tags is necessary.
  • Use truncating tag containers when you have limited space, and display of the full tags is not necessary.
  • Scrollable tag containers are a good choice when the space in a layout is limited, but viewing all the tags is essential.
Edit this page on GitHub Provide feedback on GitHub