## Import

```jsx
import { Badge } from "@cfa/react-core";
```

## Live Editor

```jsx
<Badge badgeContent={4}>
  <CalendarIcon size="md" />
</Badge>
```

## Guidelines

### When to use

- Badge is for counts on icons, buttons, tabs, or navigation items, such as unread messages or items that need attention.

### Do

- Hide the badge when the count is 0.
- Show "99+" when the count is above 99.

### Avoid

- Showing static totals when there is nothing new for people to see.
- Using Badge for long text labels. Use Chip.
- Making Badge the clickable control. Put it inside Button or Link when the whole area must be interactive.

## Composition

`badgeContent` renders the count. `children` is the anchor element the badge overlaps, such as an icon or button.

For when to use badges, see the [Badge guidelines](https://design-system.cfahome.com/components/badge).

## Examples

### Placement

Position the badge on any corner of its anchor element.

```jsx
<div style={{ display: "flex", gap: 32 }}>
  <Badge badgeContent={4} placement="topRight">
    <CalendarIcon size="md" />
  </Badge>
  <Badge badgeContent={4} placement="topLeft">
    <CalendarIcon size="md" />
  </Badge>
  <Badge badgeContent={4} placement="bottomRight">
    <CalendarIcon size="md" />
  </Badge>
  <Badge badgeContent={4} placement="bottomLeft">
    <CalendarIcon size="md" />
  </Badge>
</div>
```

### Content

Use `99+` for values larger than two digits.

```jsx
<Badge badgeContent="99+">
  <CalendarIcon size="md" />
</Badge>
```

### Border

Pass `border` to add a white border when the badge sits on a busy background.

```jsx
<div
  style={{
    display: "flex",
    gap: 32,
    backgroundColor: "#ecedee",
    padding: 32,
    width: "fit-content",
  }}
>
  <Badge badgeContent={4} border>
    <CalendarIcon size="md" />
  </Badge>
</div>
```

### Visibility

Use `hide` to show or hide the badge. When `hide` is `true`, the badge animates out; when `false`, it animates in.

```jsx
function ToggleExample() {
  const [visible, setVisible] = React.useState(true);

  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: 16,
        width: "fit-content",
      }}
    >
      <Badge hide={!visible} badgeContent={4}>
        <CalendarIcon size="md" />
      </Badge>

      <Button onPress={() => setVisible((prevState) => !prevState)} size="sm">
        Toggle
      </Button>
    </div>
  );
}
```

## Props

### Badge

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| badgeContent\* | `ReactNode` | - | The Badge content, primarily a number 0-99(+). |
| border | `boolean` | `false` | Change the border of Badge to white. |
| children | `ReactNode` | - | The content or child elements nested within this component. |
| className | `string` | - | CSS class names to apply custom styling. |
| hide | `boolean` | `false` | Set to true, to hide the component. Useful when toggling on/off. |
| id | `string` | - | The unique identifier for the DOM element. |
| placement | `"bottomLeft" \ | "bottomRight" \ | "topLeft" \ | "topRight"` | `"topRight"` | The placement of the Badge in relation to its children anchor. |
| role | `AriaRole` | - | The ARIA role assigned to the element to improve accessibility. Example roles include "button", "navigation", "dialog", etc. |
| style | `CSSProperties` | - | Inline styles specified as a React-compatible CSS properties object. |