Tag

Tags are components that are often used to label different items, create categorization, filter data, select or deselect options, and include functionality to disclose several related tags in another view. To support these different use cases, tags come in four variants—read-only, dismissible, selectable, and operational.

Use tags when content is mapped to multiple categories, and the user needs a way to differentiate between them.

Read-only, dismissible, selectable, and operational tags are all comprised of a container, a text title, and the option to add a decorative icon. Dismissible tags include an additional close icon to filter or dismiss a tag. Selectable and Operational tags include a container border to indicate at a glance that these variants have increased interactivity and function differently.

There are three different tag sizes— large, medium, and small. Use large tags when they are used as a primary task of the page or focal point, when you have more screen real estate at your disposal, or if the tag lives near other components that are also 32px in height. The medium tag size is the default size and is most commonly used. Use small tags in condensed or inline spaces.

Vertically align the tag’s container to the other components or text near it. Do not hang tag containers into grid gutters to vertically align the tag’s titles with other text on the page. When tags are placed in groups, it is recommended to have 8px of space between them on the top, bottom, left, and right.

When the tag’s title is too long to fit within the available space of its container, the title can be truncated with an ellipsis. The full title will be disclosed in a tooltip on hover. Truncation should be set at the title’s start, middle, or end, depending on what is best for the given use case.

Avoid letting long tag titles wrap to multiple lines within the tag container. This can construe the shape of the tag and the integrity of a traditional tag shape, which should be compact in form. It can also create misalignment with other tags if they are placed within a group.

For further content guidance, see Carbon’s content guidelines.

The four tag variants have different states:

For more information on tag states, see the style tab.

Read-only tags: Do not get mouse functionality besides a mouse cursor on hover and do not have interactive functionality.

Dismissible tags: Receive a mouse cursor when hovering over the title area of the tag. When hovering over the close icon, the icon gets a background color change and a mouse pointer. Once the close icon area is clicked, the tag will be dismissed, closed, or removed.

Selectable tags: Receive a full background color change and mouse pointer on hover. Clicking anywhere on the tag will put it in a selected state. Once in the selected state, clicking anywhere on the tag again will deselect it.

Operational tags: Receive a background color change and mouse pointer on hover. Clicking anywhere on the tag will disclose a way of viewing more related tags in either a toggletip, popover, modal, or breadcrumb view.

Read-only tags: Can not be operated by a keyboard and have no interactive functionality.

Dismissible tags: Receive focus on the close icon area by pressing the Tab key. Pressing the Enter or Space keys will dismiss, close, or remove the tag.

Selectable tags: The container receives focus by pressing the Tab key. Pressing the Enter or Space keys will select or deselect the tag. If navigating in a group of tags, use the Tab key to move focus to different tags in the group.

Operational tags: The container receives focus by pressing the Tab key. Pressing the Enter or Space keys will disclose additional related tags, in a toggletip, popover, modal, or breadcrumb view.

Read-only tags are not clickable and can not be interacted with. Dismissible tags have a clickable area around the close icon to dismiss or close the tag. Selectable and operational tags containers are clickable to either select the tag or view more tags.

Read-only tags are used to categorize, are used for labeling, and do not have interactive functionality. Read-only tags come in several color choices and can use optional decorative icons to delineate between multiple categories.

If your design intends to use tags as labels or for categorization, use modifiers like colors or icons to help indicate this differentiation.

Dismissible tags allow users to dismiss, close, or remove a tag. Dismissible tags are commonly used with the search component to search or filter keywords on a page or within sections of a page.

Dismissible tags can also be used as user-generated labels that are applied to instances and can be removed later if needed. Do not use a dismissible tag if the intention for it is to remain persistent at all times since they can be closed or dismissed by the user.

Selectable tags give users the ability to select or deselect them. They can be used in a form containing only tags as the selection method, in a chat to make decisions and forward the chat, and can be used as selections to filter content on a page or within a component.

In some cases, selectable tags can be used as an alternative to traditional form components when the entire form consistently uses tags as its form selection style. Selectable tags should always remain in high contrast to ensure a noticeable difference between selected and unselected tags.

When selectable tags are in groups, we recommend using horizontal alignment for easier scanning when there are only a few tags. Keep groups of tags horizontally on one line when there are six tags or less. Horizontal alignment is not recommended when there are many tags to select from in a group. Tags should wrap to form another line if there are too many to arrange horizontally on one line. If the number of tags exceeds five lines of wrapping, consider using a different component for your use case, like a multi-select dropdown.

Operational tags enable the user to see a more comprehensive view of all tags disclosed in a toggletip, popover, or breadcrumb detail view. Do not use tags as links that direct you to an entirely different page or launch you from a current experience to a separate tab.

Decorative icons lead before the tag title. Decorative icons are optional and are often used to support the tag title visually. We recommend not using decorative icons in the small tag size where there is compact spacing, which could create possible visual tension between some icon shapes and tags with borders.

Read-only, dismissible, and operational tags come in a variety of different colors, with values from the IBM Design Language color palette using component tokens. It is recommended to use multiple colors to denote different categories or labels. Selectable tags are unavailable in these colors; instead, they use core tokens.

Help us improve this component by providing feedback, asking questions, and leaving any other comments on GitHub.