The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

Tag

Figma GitHub

Used to indicate an object’s categorization.

Use tags to indicate an object’s categorization, i.e., for filtering. Use a badge instead for static metadata, status, or to indicate a new feature.

Usage

When to use

Use tags to indicate an object’s categorization, i.e., for filtering.

When not to use

  • For static metadata, status, or to display a new feature, use Badge.
  • For collection enumeration or version number, use BadgeCount.

Layout

  • The tag component can be used in several different layouts, but we commonly see them in a list or a group.
  • Tags will fill the parent container and then wrap, as necessary.

List

Layout list example

Group

Layout group example

Spacing

As a best practice, use a vertical spacing of 12px and horizontal spacing of 8px between tags.

Spacing between tags

Leading vs. Trailing Icon

The leading dismiss icon allows mouse users to clear multiple tags quicker because they do not need to move their mouse, especially when tags have a more extended width.

Do

Example of a leading icon in the tag

When the dismiss icon is trailing, the mouse user must adjust positioning to clear tags, which results in slower task completion.

Don’t

Example of a trailing icon in the tag

When content within the tag is not user-generated, it should be concise and consistent with the category name.

How to use this component

Basic use

My text tag 
<Hds::Tag @text="My text tag" @onDismiss={{this.yourOnDismissFunction}} />

In this case, since no @href or @route argument is provided it will render the tag as plain text.

Color

There are two available colors for a link: primary and secondary. The default is primary.

My link tag 
<Hds::Tag @color="primary" @text="My link tag" @route="show" @model="components/tag" @onDismiss={{this.yourOnDismissFunction}} />

Dismiss

In most cases the tag needs to be dismissable. If you don’t provide a callback function to the onDismiss argument the "dismiss/remove" button will not be rendered.

My link tag 
<Hds::Tag @color="primary" @text="My link tag" @route="show" @model="components/tag" />

Component API

Name
text
Type
string
Description
The text of the tag; or link text when the @route or @href are set. If no text value is defined an error will be thrown.
Name
href
Description
This is the URL parameter that is passed down to the <a> element.
Name
isHrefExternal
Type
boolean
Values
  • false (default)
  • true
Description
This controls if the <a> link is external and so for security reasons we need to add the target="_blank" and rel="noopener noreferrer" attributes to it.
Name
route models model query current-when replace
Description
These are the parameters that are passed down as arguments to the <LinkTo> / <LinkToExternal> components.
Name
isRouteExternal
Type
boolean
Values
  • false (default)
  • true
Description
This controls if the "LinkTo" is external to the Ember engine (more details here) in which case it will use a <LinkToExternal> instead of a simple <LinkTo> for the @route.
Name
color
Type
enum
Values
  • primary (default)
  • secondary
Description
Sets the color of a link and it is allowed only when @route or @href are set.
Name
onDismiss
Type
function
Description
The tag can be dismissed by the user. When a function is passed, the "dismiss" button is displayed.
Name
…attributes
Description
This component supports use of ...attributes.

Anatomy

Tag anatomy

Element Usage
Text Required
Icon Required for isDismissible
Container Required

Conformance rating

Conformant

When used as recommended, there should not be any accessibility issues with this component.

Best practices

  • A screen reader will read the tags from left to right, ie. "dismiss [text]".
  • Link tags and dismissible tags must be standalone elements and should not be nested inside other interactive elements because they cannot be properly accessed by a screen reader.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

  • 1.4.1 Use of Color (Level A):
    Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
  • 1.4.11 Non-text Contrast (Level AA):
    The visual presentation of the following have a contrast ratio of at least 3:1 against adjacent color(s): user interface components; graphical objects.
  • 1.4.12 Text Spacing (Level AA):
    No loss of content or functionality occurs by setting all of the following and by changing no other style property: line height set to 1.5; spacing following paragraphs set to at least 2x the font size; letter-spacing set at least 0.12x of the font size, word spacing set to at least 0.16 times the font size.
  • 1.4.13 Content on Hover or Focus (Level AA):
    Where receiving and then removing pointer hover or keyboard focus triggers additional content to become visible and then hidden, the following are true: dismissible, hoverable, persistent (see link).
  • 1.4.3 Minimum Contrast (Level AA):
    The visual presentation of text and images of text has a contrast ratio of at least 4.5:1
  • 1.4.4 Resize Text (Level AA):
    Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.
  • 2.1.1 Keyboard (Level A):
    All functionality of the content is operable through a keyboard interface.
  • 2.4.7 Focus Visible (Level AA):
    Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.
  • 3.2.1 On Focus (Level A):
    When any user interface component receives focus, it does not initiate a change of context.
  • 4.1.1 Parsing (Level A):
    In content implemented using markup languages, elements have complete start and end tags, elements are nested according to their specifications, elements do not contain duplicate attributes, and any IDs are unique.
  • 4.1.2 Name, Role, Value (Level A):
    For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.

Support

If any accessibility issues have been found within this component, please let us know by submitting an issue.

On this page: