Small label components used to display counts, status indicators, or short categorization tags alongside other UI elements.

When to Use ​

  • To display notification counts (e.g. unread messages on an inbox icon, items in a cart)
  • To indicate the status of an item (e.g. "New," "Updated," "Pending," "Live")
  • For labeling or categorizing content with very short keywords or tags
  • As a subtle visual cue to highlight a specific piece of information

When Not to Use ​

  • For lengthy text labels or detailed information — use plain text or QChip instead
  • As primary interactive elements; badges are non-interactive by default — use QButton or QChip if interaction is required
  • When the information is critical enough to warrant a more prominent component like QAlert

Component Anatomy ​

  • Container — the shaped element providing background color and padding
  • Label — concise text or number displayed inside the badge
  • Pill modifier — optional fully-rounded corners for counts or very short labels
  • Indicator variants — textIndicator and dotIndicator for notification badges positioned absolutely over a button or icon

Variants ​

Contextual badge colors convey meaning at a glance. The default variant is secondary.

Default ​

Standard rectangular badge with slightly rounded corners and secondary color.

In Buttons ​

Badges can be nested inside a QButton to display a count or status alongside the label.

Positioned ​

Use text-indicator for a count badge or dot-indicator for a silent dot, both positioned absolutely over the parent element. Always include a visually-hidden text description for screen readers.

Pill ​

Add pill for fully rounded corners — ideal for numeric counts or very short labels.

Actionable ​

Pass href to render the badge as an <a> tag. Use to for Vue Router navigation.

Props ​

PropTypeDefaultDescription
variantColorVariant | nullnullBadge color. One of primary, secondary, success, danger, warning, info, light, dark.
pillbooleanfalseFully-rounded pill shape.
tagstring"span"HTML tag for the badge container.
dotIndicatorbooleanfalseRenders as a circular dot with no text, positioned absolutely over the parent.
textIndicatorbooleanfalsePositions the badge as an absolute count indicator over the parent.
hrefstring—Renders the badge as an <a> element.
toRouteLocationRaw—Vue Router navigation target. Renders a <RouterLink>.

Accessibility ​

  • Always include a <span class="visually-hidden"> description inside dotIndicator and textIndicator badges — the visual content alone is not perceivable by screen readers
  • Do not rely on color alone to convey meaning; pair badge colors with meaningful text labels
  • When using href or to, ensure the badge text is descriptive enough to make sense out of context