Badge

Usage

import { GlBadge } from "gitlab-ui-react/badge";

<GlBadge>Maintainer</GlBadge>

Default

Use a badge to emphasize system-generated metadata such as status, progress, or product tier. Keep it next to the object it describes; use plain text when the metadata does not need emphasis.

import { GlBadge } from "gitlab-ui-react/badge";

export default function BadgeExample() {
  return (
    <GlBadge>Badge</GlBadge>
  );
}

Variants

Choose a variant for the metadata’s meaning. Neutral is the default, info indicates noteworthy or active progress, success indicates a desired result, warning signals a non-critical problem, danger identifies a critical problem, and tier identifies a product tier.

import { GlBadge } from "gitlab-ui-react/badge";

export default function BadgeVariantsExample() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <GlBadge variant="neutral">Neutral</GlBadge>
      <GlBadge variant="info">Running</GlBadge>
      <GlBadge variant="success">Passed</GlBadge>
      <GlBadge variant="warning">Pending</GlBadge>
      <GlBadge variant="danger">Failed</GlBadge>
      <GlBadge variant="tier">Ultimate</GlBadge>
    </div>
  );
}

Icons

Add an icon only when it reinforces or directly communicates the metadata. An icon-only badge requires an aria-label that describes its meaning rather than the icon’s name.

import { GlBadge } from "gitlab-ui-react/badge";

export default function BadgeIconsExample() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <GlBadge icon="issue-open-m" variant="success">Open</GlBadge>
      <GlBadge icon="issue-close" variant="info">Closed</GlBadge>
      <GlBadge aria-label="Scheduled" icon="calendar" variant="neutral" />
    </div>
  );
}

Links

Set href when the badge should navigate to the object it describes. Otherwise, badges are static and should not be used as buttons.

import { GlBadge } from "gitlab-ui-react/badge";

export default function BadgeLinkExample() {
  return (
    <GlBadge href="#pipeline" icon="status_success" variant="success">
      Pipeline passed
    </GlBadge>
  );
}

Accessibility

• Keep the badge beside the content it describes. If that relationship is not clear, associate the content with the badge using aria-describedby.
• Give icon-only badges a descriptive aria-label. They automatically receive role="img"; icons next to visible text are hidden from assistive technology.
• Add visually hidden context when a value is ambiguous on its own, such as explaining what a numeric badge counts.
• Do not rely on color alone to communicate a badge’s meaning.
• Use href only for navigation and provide a meaningful destination.

API

These are the component-specific props. GlBadge also forwards supported DOM attributes and exposes a ref to the rendered element.

Related resources

• Badge in the Pajamas Design System
• Badge stories in Storybook
• Badge source and complete TypeScript props