Tag is a container for a piece of data that can be used either as an interactive element or as a visual treatment.

As an interactive element, Tag displays data in a pill-shaped container, along with a Close icon for easy user removal. As a visual treatment, Tag can be used to denote an item's status or category by displaying short text in a color-coded, pill-shaped container.

Tag can be used on its own or with another component like Multiselect. Static, visual Tags can be paired with Tooltip to display additional information.

•  As an interactive element, Tags with a Close icon appear on page load or are added via user selection.
  • Hovering over an interactive Tag displays a browser-based tooltip with the full tag content. 
  • To remove an interactive Tag:
    • On desktop: the user clicks the Close icon or navigates to the Tag and presses the Spacebar.
    • On mobile: the user taps anywhere on the Tag.
• As a visual treatment, Tag appears near an item on the page to indicate the item’s status, category, or other attribute.
  • If paired with Tooltip, additional information appears on hover.

• As an interactive element:
  • To add filters to a table or search results 
  • To display user selections
• As a visual treatment:
  • To label or indicate the status, category, or other aspect of an item on the page
  • To make it easier to scan items in a table

• For important messages or alerts
• In tables or lists where all items have the same status, making it redundant

Tag has 2 text styles:

• Impact (uppercase) is recommended for use in visual Tags (previously called 'status' tags).
• Default (sentence case) is recommended for use in interactive Tags (previously called 'removable' tags).

Tag has 3 sizes:

• Large (24 px height) is best for interactive tags with single words and for mobile interfaces, as it has a larger tappable area.
• Medium (20px height) is the suggested default size for both interactive and visual Tags, has tighter padding than Large size for a smaller visual footprint or to fit more Tags in a container.
• Small (16px height) uses a shorter height and smaller font size. This size should only be used as an interactive Tag with caution due to its small clickable area.

Colors and emphasis

Tag is available in several color types:

• Default (Non Alert) Colors:
  • Default (gray) is the recommended color for interactive (formerly removable) Tags or for statuses like “To Do” and “Scheduled".
• Alert (Semantic) Colors: 
  • New (peacock) is for statuses like “New” and “Unread”.
  • Positive (green) is for statuses like “Completed” and “Approved".
  • Attention (yellow) is for statuses like “Warning" and “Issue Detected".
  • Critical (red) is for statuses like “At Risk”. This color is reserved for the highest risk and most severe issues, like patient safety matters.
• Secondary Colors (Non Alert):
  • Blue
  • Orchid-40
  • Pistachio-40
  • Purple-40
  • Yellow-40

Creating a list of terms and assigning colors

In visual Tags, Tag text is usually a term from a list of statuses, a set of categories, or a taxonomy (e.g., appointment types, claim statuses, disease classifications). However, you may need to create a list of terms that fits your use case.

When creating your own list:

• Consider the possible terms and keep your list as short as possible. After the initial release, update it only when necessary. New terms interfere with users’ ability to scan items quickly.
• Assign only one color to a term and use color/term pairs consistently.
• Only use alert colors for alert meanings. i.e. only use 'Positive' color for a successful or positive status.
• Don't use multiple colors with the same term (e.g., don’t use the term “Inpatient” in an Orchid-40 Tag in one location and then in a red StatusTag in another location). Consistency is an important part of both the user experience and accessibility.
• Consider including a legend or key for the full list of terms, especially if they’re app-specific or if users might need to refresh their memory.

Interactivity

Tag can allow users to view and remove data points or filters from a list. When users click or activate the optional Close icon, Tag disappears; apart from this, it isn’t interactive. However, removing a Tag may trigger a page update (e.g., when removing a filter refreshes search results on the page).

For non-interactive Tags, you can use Tooltip in addition to the Tag for the option to display more information, like item status details.

Tag width is dictated by the length of the text it contains. Tag automatically truncates text longer than 29 characters with an ellipsis (...) to prevent wrapping on narrow screens. In truncated instances of Tag, hovering over a tag displays a browser-based tooltip with the full tag content. (Known issue: Full text is not displayed on keyboard focus.) To prevent truncation, read the developer tips section.

When using Tag as a visual treatment:

• Tag should appear as close as possible to the item it relates to. In general, it should be placed to the right of the item so that the user can read the item first and then view its status.
• In a table, Tag can be placed farther away from its corresponding item, since the shared row indicates that they’re related.

Using Tag as a visual treatment:

• Use text only, no graphics.
• Keep text short (1-3 words) to avoid lengthy tags or wrapping.
• Use the uppercase text styling option. This helps differentiate visual tags from other elements on the page.

Using Tag as an interactive element:

• Content is limited to text only (no icons or images). This reduces visual clutter and makes it easier to scan a collection of interactive Tags.
• Use sentence case  text styling for interactive tag text:
  • “Asthma”, not “asthma”
  • “Patient name”, not “Patient Name”
• Use text truncation on interactive tags:
  • Text longer than 29 characters is automatically truncated with an ellipsis (…). The full text is visible on hover. (Known issue: Full text is not visible on keyboard focus.)
• If the interactive Tag represents a user selection, it should contain the exact same text as the user selection. For example, if users select “Primary care provider” from a list, the Tag should contain the text “Primary care provider”, not “PCP” or another shortened version.

The CSS text-transform attribute automatically styles StatusTag’s text in all caps, so you don’t need to enter the text in all caps when setting the text prop.

Known issue

One value for the color prop doesn’t match the Forge alert types. For a Success StatusTag, set color='positive'. In addition, the info Forge alert color isn’t available for this component.

Truncation

By default, text is limited to 29 characters. At 30 characters or more, text is truncated with an ellipsis (...). Although not generally recommended, you can override this in CSS by setting max-width for the .fe_c_tag__text element (with CSS specificity of at least 2 classes). It is currently set to 30ch, setting that to a number higher than 30 will get you more characters before truncation.

Implementation links

Tag directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessability in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Tag } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Tag from '@athena/forge/Tag';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Tag from '@athena/forge/dist/Tag';