;
};
Badges provide a compact visual cue for status, presence, or counts without taking up much space. They work best when attached to another element such as an icon, avatar, or navigation item so the meaning is immediately clear.
Use [Tag](/components/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
Use an empty badge to communicate presence, availability, or a lightweight status when a number is not needed.
Use badge content to show the number of notifications, tasks, or updates associated with another element.
Use semantic badge colors consistently to communicate informational, positive, warning, or error states.
## Anatomy
A badge is a compact surface with optional slotted content. When no content is provided, it renders as a dot indicator. When content is present, it expands to hold the number or short label.
| Part | Element | Description |
| ----- | ------- | ----------------------------- |
| **1** | Base | The container surface |
| **2** | Content | Optional number or short text |
## Design guidelines
### Size
Badge dot size is controlled by the `size` 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.
When a count exceeds what fits, show `99+` or a similar capped value. The `+` signals overflow without needing an exact number.
## 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.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBadge } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBadge } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBadge],
template: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
`small` is the default size, so you only need to set `size="medium"` when you want a larger indicator.
### 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.
2
12
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
212
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBadge } from "@beeq/react";
212
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBadge } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBadge],
template: `
212
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
212
```
## 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 |
Check the [Status](/components/status) component for more details on semantic color usage and meaning in BEEQ.
### 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.
.badge--icon {
position: relative;
display: inline-flex;
& bq-badge {
position: absolute;
inset-block-start: -4px;
inset-inline-end: -4px;
}
}
```
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
Do
Use the supported badge sizes so indicators stay visually consistent across the product.
Don't
Do not resize badges arbitrarily. Oversized indicators quickly feel noisy and unbalanced.
Do
Show a badge only when there is relevant status or count information to communicate.
Don't
Do not leave empty or unnecessary badges in the interface when there is nothing meaningful to show.
Do
Place attached badges on the outer edge of the related icon or trigger so both elements remain visible.
Don't
Do not center a badge over the element it refers to. It can obscure the symbol and reduce clarity.
Do
Pair badges with another UI element so the status or count has clear context.
Don't
Do 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
| Variable | Description | Default |
| ------------------------------ | ----------------------------------- | ---------------------------- |
| `--bq-badge--background-color` | Badge background color | `var(--bq-ui--danger)` |
| `--bq-badge--box-shadow` | Badge box shadow | `none` |
| `--bq-badge--border-color` | Badge border color | `var(--bq-stroke--tertiary)` |
| `--bq-badge--border-radius` | Badge border radius | `var(--bq-radius--full)` |
| `--bq-badge--border-style` | Badge border style | `none` |
| `--bq-badge--border-width` | Badge border width | `0` |
| `--bq-badge--size-small` | Small badge size | `8px` |
| `--bq-badge--size-medium` | Medium badge size | `12px` |
| `--bq-badge--size-large` | Minimum size used by content badges | `16px` |
| `--bq-badge--text-color` | Badge text color | `var(--bq-text--alt)` |
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore badge states and examples in Storybook
View the component source on GitHub
Badges provide a compact visual cue for status, presence, or counts without taking up much space. They work best when attached to another element such as an icon, avatar, or navigation item so the meaning is immediately clear.
A badge is a compact surface with optional slotted content. When no content is provided, it renders as a dot indicator. When content is present, it expands to hold the number or short label.
| Part | Element | Description |
| ----- | ------- | ----------------------------- |
| **1** | Base | The container surface |
| **2** | Content | Optional number or short text |
## Design guidelines
### Size
Badge dot size is controlled by the `size` prop. Choose the size based on how much visual weight the indicator should carry in context.