> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/badge.md).

# Badge

The Avonni Badge component is a compact visual indicator that highlights status, categories, or metadata with a short, color-coded label. Use it when you need to draw attention to a single piece of information; for multiple items, use the [**Chip Container**](/dynamic-components/components/chip-container.md) component instead.

{% hint style="warning" %}
The Badge component is designed to display a single item or piece of information. If you need to display multiple items as badges, consider using the [**Chip Container**](/dynamic-components/components/chip-container.md) component instead.
{% endhint %}

## Overview

The Avonni Badge component adds colorful, eye-catching labels to highlight information in your Salesforce Dynamic Components. It displays short text, numbers, or phrases, supports color-coded style variants for different connotations, and can include an optional avatar (icon, image, or initials) for added context.

Key features include:

* **Concise Labels:** Display short text, numbers, or phrases.
* **Style Variants:** Color-coded options for different connotations (e.g., success, warning).
* **Optional Avatar:** Add icons, images, or initials for context.
* **Attention-Grabbing:** Enhances UI clarity and visual appeal.

### Use Cases

* **New Item Indicators:** Flag new products, features, or content (e.g., "New").
* **Notification Counts:** Show unread messages or alerts (e.g., "5+").
* **Product Labels:** Categorize items like "Sale," "Bestseller," or "New Arrival."
* **User Status:** Display roles or states (e.g., "Online," "Admin").
* **Status Markers:** Indicate process stages (e.g., "Approved," "Pending").

## Configuration

To configure the Badge, select it on the canvas. The **Edit Badge** panel opens on the right with two tabs: **Properties** and **Style**. The sections below mirror the Properties tab.

### Properties

#### Label

The **Label** is the text displayed inside the badge. Keep it short and purposeful. You can type a static value or bind the label to a variable, formula, or record field so it updates dynamically — for example, showing a live notification count or a record's status.

#### Outline

When **Outline** is enabled, the badge is rendered with an outline style rather than a solid fill. This is off by default.

#### Variant

The **Variant** sets the color and visual style of the badge so you can align it with its meaning. Choose the variant that matches the intent of the information being shown — for example, **Success** for a positive state or **Error** for a problem.

Available variants: **Base** (default), **Alt-Inverse**, **Brand**, **Error**, **Info**, **Inverse**, **Offline**, **Success**, and **Warning**.

#### Avatar

The **Avatar** section adds an optional visual element to the badge for extra context. It exposes the following settings:

* **Variant:** Sets the shape of the avatar — **Circle** or **Square** (default).
* **Initials:** Text initials to display when no image is provided.
* **Icon Name:** A Lightning Design System icon used as a fallback when no image or initials are available (e.g., `standard:user`).
* **Image Source:** The URL of an image to display. You can select an uploaded image or bind a URL.

{% hint style="info" %}
**Best Practice**

Use avatars when linking to users or objects; an icon serves as a fallback when there is no image or set of initials. Adjust avatar styling and look and feel from the [Style Panel](/dynamic-components/component-builder/configuring-components/style.md) (e.g., borders, shadows, colors).

<img src="/files/yv7QXUzJkP57WGQh20Sk" alt="" data-size="original">
{% endhint %}

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

### Example 1: Simple Status Badge

1. Configure the properties:
   * **Label:** "Approved"
   * **Variant:** Success

**Result:** A green badge highlighting positive status, e.g., on a record.

<figure><img src="/files/1GrVneNQugxQ3UcffJoC" alt=""><figcaption></figcaption></figure>

### Example 2: Notification Count with Avatar

1. Create a Number variable, `unreadCount`.
2. Configure the properties:
   * **Label:** `{!unreadCount}`
   * **Variant:** Warning
   * **Avatar Icon Name:** `standard:scan_card` (or bind an image URL)
   * **Avatar Variant:** Circle

**Result:** A dynamic yellow badge showing the count with an icon, updating via the variable.

<figure><img src="/files/3wOLp5oyZmQbQOWPcwe7" alt=""><figcaption></figcaption></figure>

### Example 3: User Role Badge

1. Configure the properties:
   * **Label:** "Admin"
   * **Variant:** Info
   * **Avatar Initials:** "AD"
   * **Avatar Variant:** Square

**Result:** A badge with initials for role indication in profiles.

<figure><img src="/files/dlRqEPMhsueY59Ns5jjB" alt=""><figcaption></figcaption></figure>

## Styling

The **Style** tab gives you fine-grained control over the Badge's appearance, overriding the default variant styles. Configure it from the **Style** tab of the Edit Badge panel. The available sections depend on the selected **Variant**.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the badge, creating space between it and other elements on the screen.

* **Top / Right / Bottom / Left:** Adjust the space on each side of the badge.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing between the badge's content and its border.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the badge.

* **Color:** Set the border color.
* **Size:** Adjust the border thickness.
* **Style:** Choose a border style (e.g. solid, dashed, dotted).
* **Radius:** Control the roundness of the corners.
  {% endtab %}

{% tab title="Horizontal Alignment" %}
Controls how the badge is aligned horizontally within its container.

* **Horizontal Alignment:** Set the badge's horizontal position.
  {% endtab %}

{% tab title="Chip" %}
Customizes the badge label and its frame.

* **Label Font Size / Label Font Weight / Label Font Style:** Style the badge text.
* **Border Size / Border Style / Border Radius:** Customize the badge frame.
* **Line Height:** Adjust the height of the label line.
  {% endtab %}

{% tab title="Avatar" %}
Customizes the optional avatar shown inside the badge.

* **Border Size / Border Color / Border Style:** Customize the avatar border.
* **Initials Font Color / Initials Font Color Hover / Initials Font Weight / Initials Font Weight Hover:** Style the avatar initials.
* **Icon Background Color / Icon Foreground Color:** Set the avatar icon colors.
* **Image Object Fit:** Control how an avatar image fits its frame.
  {% endtab %}

{% tab title="Variant Colors" %}
Sets the badge colors for the selected variant. The same set of options is shown for whichever variant is active (set per variant: Base, Brand, Error, Info, Inverse, Alt-Inverse, Offline, Success, Warning).

* **Background:** Set the badge background color.
* **Border Color:** Set the badge border color.
* **Text Color:** Set the label text color.
* **Outline Text Color:** Set the label text color when **Outline** is enabled.
  {% endtab %}
  {% endtabs %}

## Troubleshooting Common Issues

* **Badge Not Visible** — Check the Variant setting for hidden or low-contrast styles; ensure the Label field is not empty.
* **Avatar Not Loading** — Verify the Image Source URL is publicly accessible or that the Icon Name uses the correct format (e.g., `standard:user`); test bindings with a static value first.
* **Overly Long Label** — Badges truncate long text; keep labels short and concise.
* **Color Clashes** — Preview in different themes and adjust the Variant to ensure sufficient contrast and readability.
* **Bindings Not Updating** — Confirm the Label or Avatar fields are bound to variables or formulas; use the [debug panel](/dynamic-components/component-builder/advanced-features/debug-panel.md) in preview mode to inspect values.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/badge.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.