Use Tag when the element needs to be interactive, dismissible, or read as a standalone labeled item. Badges are non-interactive indicators.
When to use
Use badges when
- You need to show a small count, status, or presence indicator
- The badge is tied to another UI element such as an icon, avatar, or label
- The information should be noticeable without dominating the layout
Do not use badges when
- The content needs to be clicked, dismissed, or filtered
- The message is essential enough that it should appear as regular text
- Adding the badge would create clutter or repeat information the UI already communicates clearly
Badge patterns
Dot indicator
Use an empty badge to communicate presence, availability, or a lightweight status when a number is not needed.
Counter
Use badge content to show the number of notifications, tasks, or updates associated with another element.
Semantic status
Use semantic badge colors consistently to communicate informational, positive, warning, or error states.
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Base | The container surface |
| 2 | Content | Optional number or short text |
Design guidelines
Size
Badge dot size is controlled by thesize prop. Choose the size based on how much visual weight the indicator should carry in context.
The
size prop only applies when the badge has no content. When you add slot content — a number or short label — the badge ignores size and auto-expands to fit the text.| Size | Diameter | When to use |
|---|---|---|
small | 8px | Default. Use in dense or compact layouts where a subtle dot signal is enough. |
medium | 12px | Use when the badge needs slightly more presence, such as next to larger icons or in less crowded layouts. |
Content length
Keep counter content short — three characters maximum, including the+ symbol.
Usage
Dot indicator
Use the badge without slot content when you only need a small visual signal.size matters most in this variant because it controls the dot diameter.
Counter
Add slot content when the badge needs to communicate a count. Keep the value short and meaningful so the badge stays compact and easy to scan.Options
Color
Badge color should reinforce meaning, not create it on its own. Keep semantic usage consistent so people learn what each color communicates across the product.| Color | Typical meaning |
|---|---|
default | Neutral presence or a generic indicator when no semantic state is needed |
ui--info | Informational updates or newly available information |
ui--success | Positive status, availability, or successful completion |
ui--warning | Caution, review needed, or temporary attention |
ui--danger | Errors, urgent issues, or disruptive states |
Attached to an icon
When a badge is paired with an icon or trigger, position it on the outer edge so it remains visible without covering the main symbol.To create a “cutout ring” effect — useful when a badge sits on top of an image or avatar — add a border using the
--bq-badge--border-color, --bq-badge--border-style, and --bq-badge--border-width CSS custom properties. Match the border color to the surface behind the badge for a clean visual separation.Best practices
DoUse the supported badge sizes so indicators stay visually consistent across the product.
Don’tDo not resize badges arbitrarily. Oversized indicators quickly feel noisy and unbalanced.
DoShow a badge only when there is relevant status or count information to communicate.
Don’tDo not leave empty or unnecessary badges in the interface when there is nothing meaningful to show.
DoPlace attached badges on the outer edge of the related icon or trigger so both elements remain visible.
Don’tDo not center a badge over the element it refers to. It can obscure the symbol and reduce clarity.
DoPair badges with another UI element so the status or count has clear context.
Don’tDo not rely on a standalone badge in product UI unless its meaning is obvious from nearby content or a legend.
Accessibility
Badges are visual indicators, not interactive controls. When a badge communicates count or status, make sure the surrounding element or nearby text also exposes that meaning to assistive technologies. Do not rely on color alone. Use text, labels, or accessible names on the related control when the badge carries important information such as unread notifications or an error state.API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
backgroundColor | background-color | Badge background color token | string | undefined |
size | size | Dot size when no content is provided | 'small' | 'medium' | 'small' |
textColor | text-color | Text color token used when content is present | string | undefined |
Slots
| Slot | Description |
|---|---|
| default | Optional number or short text shown inside the badge |
Shadow parts
| Part | Description |
|---|---|
base | The visible badge wrapper |
number | The element wrapping the default slot content |
CSS custom properties
Resources
Interactive playground
Explore badge states and examples in Storybook
Source code
View the component source on GitHub