Label

Examples

<gl-label background-color="#D9C2EE" title="Label title" target="#" />

<gl-label background-color="#D9C2EE" title="scoped::label" target="#" scoped />

<gl-label background-color="#D9C2EE" title="Label title" target="#" show-close-button />

<gl-label
  background-color="#D9C2EE"
  title="Label title"
  description="Description text"
  target="#"
/>

<gl-label
  background-color="#D9C2EE"
  title="Label title"
  description="Description text"
  target="#"
  footer="Footer text"
/>

View in Pajamas UI Kit →

Structure

Guidelines

When to use

• To categorize objects like issues, merge requests, and epics with user-defined tags.
• When a user needs to manually organize and filter content by custom categories.
• To visually group related items across different views using a consistent color and name.
• When mutually exclusive categorization is needed, use scoped labels (for example, workflow::in review and workflow::ready for design cannot coexist on the same object).

When not to use

• If displaying more generic object metadata that are not categories, consider using badges.

Variants

1. Scoped Labels: Scoped labels are a unique type of label, characterized by their mutually exclusive behavior. Each scoped label has a key and a value. An issue, epic, or merge request can only have one scoped label of a specific key. For example, if an issue has the label workflow::ready for design, it cannot have any other workflow:: labels at the same time. Applying a second workflow:: label will automatically replace the former. A scoped label is visually differentiated from a regular label by the contrasting colors on the left and right sides of the label.

Behavior

• Clicking on a label filters the view, or navigates the user to a list view filtered by that label.
• Users can manually filter lists and other types of views by labels.
• Labels can include a close icon that, when clicked, remove the label from the interface.

Content

Description

• A label's description is shown in a tooltip when hovering the label.

Footer

• In addition to the description, a label may require footer content in the tooltip shown when hovering the label. For example, if the label is archived.

Accessibility

• Label title must be present. Title is the visible text and accessible name.
• Labels that function as links must be unique and descriptive so a screen reader user understands where the link leads.
• When a label includes a close button, the button must have an accessible name (for example, aria-label="Remove label: Label title") so a screen reader user knows which label will be removed.
• A label's description is surfaced in a tooltip. Ensure the tooltip is accessible to keyboard and screen reader users.

Keyboard navigation

• Label links can be focused with Tab and activated with Enter.
• Close buttons can be focused with Tab and activated with Enter or Space.

Code reference

GlLabel

import { GlLabel } from '@gitlab/ui';