> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Badge - Web

> Badges are used to indicate that something requires a user's attention on an interactive element.

> [!NOTE]
>
> For development, import `Badge` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3?node-id=2611-49568).

![](https://mintcdn.com/servicetitan/uz2PQSvO75TRhQ38/images/docs/web/components/shared/overview-of-a-badge.png?fit=max\&auto=format\&n=uz2PQSvO75TRhQ38\&q=85\&s=58c66b481011a0dddc99702f8437f188)

## Anatomy

The Badge consists of two primary elements that work together to indicate attention requirements on interactive elements.

![Anatomy of a
Badge](https://mintcdn.com/servicetitan/Ni0bXIw9diilEZPZ/images/docs/web/components/badge/design/anatomy-of-a-badge.png?fit=max\&auto=format\&n=Ni0bXIw9diilEZPZ\&q=85\&s=c22d0722b93b176b9282231688714834)

1. Parent element
2. Badge

## Options

The Badge supports default and value-less configurations to accommodate various notification scenarios.

### Default

badge-options-default

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-options-default?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="with 6 unread">6</Badge>
    </Button>
  );
}

export default App;
```

By default, show the number of alerts or notifications on the Badge so users see them without diving deeper.

### Without value

badge-options-without-value

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-options-without-value?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="has unread notifications" />
    </Button>
  );
}

export default App;
```

When the number of alerts or notifications is not available, use an empty Badge.

## Behavior

The Badge responds to value limits and positioning requirements while maintaining consistent visual indication.

### Max value

badge-behavior-max-value-do

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-behavior-max-value-do?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="with 99+ unread">99+</Badge>
    </Button>
  );
}

export default App;
```

> [!TIP]
>
> **Do**

Set a max value for Badges. Use 99 in most cases. When values of 100+ are frequent, use 999.

badge-behavior-max-value-dont

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-behavior-max-value-dont?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="with 999999999 unread">999999999</Badge>
    </Button>
  );
}

export default App;
```

> [!CAUTION]
>
> **Don't**

### Offset

When using Badge with components like [Link](https://anvil.servicetitan.com/docs/components/link/design), overlap may not be ideal. Set offset to resolve this issue.

badge-offset

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-offset?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Link } from "@servicetitan/anvil2";

function App() {
  return (
    <Link href="#" style={{ position: "relative" }}>
      What&apos;s new?
      <Badge
        aria-label="with 12 updates"
        offset={{
          x: "1rem", // 16px to the right
          y: "-0.25rem", // 4px up
        }}
      >
        12
      </Badge>
    </Link>
  );
}

export default App;
```

> [!TIP]
>
> **Do**

badge-behavior-offset-dont

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-behavior-offset-dont?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Link } from "@servicetitan/anvil2";

function App() {
  return (
    <Link href="#" style={{ position: "relative" }}>
      What&apos;s new?
      <Badge aria-label="with 12 updates">12</Badge>
    </Link>
  );
}

export default App;
```

> [!CAUTION]
>
> **Don't**

## Usage Guidelines

| Standard | Requirement |
| - | - |
| DoIndicate something requires attention | Use a Badge to indicate to users that something requires attention. |
| Don'tLabeling or organizing information | Badges should not be used to label or organize information, instead use a [Chip](https://anvil.servicetitan.com/docs/components/chip/web.md). |
| Don'tCounting items within an element | Badges should also not be used to indicate the count of items within (e.g., the number of items inside of a Tab or folder). Use a Chip for these cases. |
| Don'tChanging the Badge color | Badges should only use their default color; see [Do not change the color of the Badge](#do-not-change-the-color-of-the-badge). |
| Don'tNon-numerical values | Badges should only contain numerical values; see [Only use numbers inside of a Badge](#only-use-numbers-inside-of-a-badge). |

### Alternatives

#### Badge vs Chip

Chips are used to categorize, label, and add context to items whereas Badges are used to indicate something requires attention, such as a notification. Additionally, Chips can be interactive while Badges are not.

### How to Use

#### Add Badge to interactive elements

badge-options-default

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-options-default?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="with 6 unread">6</Badge>
    </Button>
  );
}

export default App;
```

Attach Badges to interactive elements, such as icon buttons, to indicate a count (e.g., the number of notifications).

#### Without a count

badge-options-without-value

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-options-without-value?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="has unread notifications" />
    </Button>
  );
}

export default App;
```

Use Badges without a value to denote an unread notification or message.

#### Do not change the color of the Badge

![Badge how color
dont](https://mintlify.s3.us-west-1.amazonaws.com/servicetitan/images/docs/web/components/badge/web/badge-how-color-dont.png)

> [!CAUTION]
>
> **Don't**

#### Only use numbers inside of a Badge

badge-non-number-dont

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-non-number-dont?file=src/App.tsx)

```tsx lines theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Button
      <Badge aria-label="with new notification">New Item</Badge>
    </Button>
  );
}

export default App;
```

> [!CAUTION]
>
> **Don't**

Badges should only contain numerical values.

## Content

Content within the Badge should clearly indicate the count or presence of items requiring attention through numerical values.

## Keyboard Interaction

Users can navigate the Badge using standard keyboard controls.

For accessibility, `aria-label` should be defined to match the context.

With the example above, there are 2 methods:

* Adding `aria-label="Cases with 6 items to review"` to the Button
  * This will read as "Cases with 6 items to review, button"
* Adding `aria-label="with 6 items to review"` to the Badge only
  * This will read as "Cases, button, with 6 items to review"

For more guidance on accessible labels and ARIA, see [labels and CTA best practices](https://anvil.servicetitan.com/docs/accessibility/labels-and-ctas.md).

## Code

**Implementation**

badge-playground

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-playground?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Badge, Flex, Button } from "@servicetitan/anvil2";
import Warning from "@servicetitan/anvil2/assets/icons/material/round/warning.svg";

function App() {
  return (
    <Flex gap="6">
      <div style={{ display: "inline-block", position: "relative" }}>
        <Button icon={Warning} />
        <Badge aria-label="with 4 notifications">4</Badge>
      </div>
      <Button>
        What&apos;s new?
        <Badge aria-label="with notifications" />
      </Button>
    </Flex>
  );
}

export default App;
```

## Common Examples

```tsx theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  return (
    <Button style={{ position: "relative" }}>
      Alerts
      <Badge aria-label="with 12 unread">12</Badge>
    </Button>
  );
};
```

### Use relative positioning on badge parent

In order for a badge to properly position itself, the parent of the `Badge` component that the badge should be placed on needs to have `position: relative`.

```tsx theme={null}
<div style={{ position: "relative " }}>
  Content
  <Badge aria-label="with 10 notifications">10</Badge>
</div>
```

### Adjusting badge position

When used with square or rectangular elements, the badge should position itself nicely on the corner of the element. Sometimes, some fine-tuning may be required if the element has a different shape, such as text. Use the `offset` prop to supply CSS sizing values to the `x` and `y` parameters.

badge-offset

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-offset?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Badge, Link } from "@servicetitan/anvil2";

function App() {
  return (
    <Link href="#" style={{ position: "relative" }}>
      What&apos;s new?
      <Badge
        aria-label="with 12 updates"
        offset={{
          x: "1rem", // 16px to the right
          y: "-0.25rem", // 4px up
        }}
      >
        12
      </Badge>
    </Link>
  );
}

export default App;
```

### Badges without children

If no `children` element is provided for the `Badge` component, only a red dot will appear.

badge-children

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/badge-children?file=src/App.tsx)

```tsx lines expandable theme={null}
import { Badge, Button } from "@servicetitan/anvil2";

function App() {
  return (
    <Button style={{ position: "relative" }}>
      Notifications
      <Badge aria-label="has unread notifications" />
    </Button>
  );
}

export default App;
```

## React Accessibility

### Using aria-label

```tsx theme={null}
<Badge aria-label="12 unread">12</Badge>
```

> [!TIP]
>
> **Do**

Use the aria-label prop to provide better context for the number displayed within the badge.

```tsx theme={null}
<Badge>12</Badge>
```

> [!CAUTION]
>
> **Don't**

Provide only the children for screen readers to use.

For more guidance on accessible labels and ARIA, see [labels and CTA best practices](https://anvil.servicetitan.com/docs/accessibility/labels-and-ctas.md).

**Badge Props**

```tsx theme={null}
<Badge offset={{ x: "0.5rem", y: "0.5rem" }} aria-label="12 unread">
  12
</Badge>
```

## `Badge` Props

In addition to the props listed below, the `Badge` component can accept any valid HTML `sup` props.

**offset** `\{ x?: string; y?: string \}`

Fine-tune the badge position with CSS sizing values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.