Version 6.0.0

Tag

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

Search field shown with five removeable tags filtering the search. Search field shown with five removeable tags filtering the search.

Anatomy#


Image illustrating through labels the component parts of a tag, including the label, the optional close icon. Image shows two or more tags makes a tag group.

Options#


Key example of a tag with "traveling" as its label.

Label#

Tags should always include a label. These can represent search terms, filters, or keywords.

Key example of a tag with an avatar.

Avatar#

Tags have the option to include an avatar in addition to the label. These should be used to represent entities.

Key example of two tags. One without a close icon that cannot be removed, and another with a close icon that can be removed.

Removable#

Tags have the option to be removable or not. Removable tags have a small close (“x”) button.

Key example of two tags in error state. One has only a label, the other has an avatar, label, and a close icon.

Error#

A tag can be marked as having an error to show that it has become invalid.

Key example of two disabled tags.

Disabled#

A tag in a disabled state shows that a tag exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a tag may become available later.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
label
text
has avatar
yes / no
no
is removable
yes / no
no
is error
yes / no
no
is disabled
yes / no
no

Behaviors#


Key example of a single tag with truncated label text.

Text overflow#

When the tag text is too long for the available horizontal space, it truncates. The full text should be revealed with a tooltip on hover.

Key example of five tags in a tag group that overflow by wrapping to a second line.

Tag group overflow#

When horizontal space is limited in a tag group, the individual tags wrap to form another line.

Usage guidelines#


Allow bulk actions#

In some instances, it's possible to add an action next to a group of tags to provide a way to easily take an action on the entire group at once. Make sure to reveal the action only when there is more than one tag displayed.

Key example of a bulk action for "clear all" included at the end of a tag group.

Avoid disabling a large group of tags#

In cases where users cannot interact with a large group of tags, consider hiding the group and its greater construct rather than disabling all of the individual tags.

Key example showing a group of tags that are all disabled, which is not recommended.

Internationalization#


Key example of three different tags and how they should be ordered in right-to-left languages, close icon on the left, label in the middle, and avatar on the right, if applicable.

RTL#

For RTL (right-to-left) languages, the layout of the tag is mirrored. The avatar is right-aligned and the close button is left-aligned.

Keyboard interactions#


KEYINTERACTION
TabTabbing into a group of tags places the focus on the first tag (only one tag receives the keyboard focus at a time).
Left, Right, Up, Down ArrowsMoves focus through the group of tags.
Page Up or Page DownMoves focus to the previous or next tag in the group (last becomes first, and first becomes last).
Home or EndMoves focus to the first or last tag in the group.
Backspace, Delete, or SpaceRemoves the tag in focus from the group.

Changelog#


DateNumberNotes
Sep 11, 20196.0.0
  • Renamed "deletable" option to "removable"
Aug 22, 20195.1.0
  • Added text overflow behavior
Apr 19, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added RTL (right-to-left) guidelines

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Downloadable UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.