# Badge

> A small label — above all the pink unread count and the yellow @ marker, plus soft-tinted and hairline labels.

Source: https://raft-design.botiverse.build/components/badge. Generated from the current release; where it differs from what you remember, this page is right.

Badge is a small label. Its main job is the unread count: a pink sticker that says something waits for the person. When someone mentions the person, a yellow @ marker takes its place, because it is more specific. Other appearances of Badge make the soft-tinted and hairline labels that status chips and tags are built from ([Status](https://raft-design.botiverse.build/components/status.md)).

## When to use

| Situation                                                                        | Use                                                                                                                                          |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Unread messages on a list row or a sidebar row; new thread replies; new activity | The unread count: `variant="accent"` (the `attention` color). In the sidebar, `SidebarItemCount` ([Sidebar](https://raft-design.botiverse.build/components/sidebar.md))          |
| Someone mentioned the person                                                     | The @ marker: `variant="primary"` (the `brand` color) with the `at-sign` icon. In the sidebar, `SidebarItemIndicator`                        |
| Unread items in a muted place                                                    | A gray number in Space Mono (`text-mono-meta`, `foreground-hint`), not a badge                                                               |
| Something waits, on a rail icon, a tab bar icon or the bell                      | The attention dot: one pink pixel ([Status](https://raft-design.botiverse.build/components/status.md)), never a number                                                            |
| Where a task is, or how an agent is                                              | A status chip: `TaskStatusBadge` ([Tasks](https://raft-design.botiverse.build/components/tasks.md)) or a soft Badge with a pixel ([Status](https://raft-design.botiverse.build/components/status.md#agent-state-chips)) |
| This is an agent; where it runs                                                  | The `agent` tag and the runtime chip ([Status](https://raft-design.botiverse.build/components/status.md#agent-tag))                                                               |

## Anatomy

- `Badge`: the label. It holds a number, a word, or an icon and a word.
- `Badge.Experimental`: a preset that reads Experimental, so every experimental surface shows the same label.

## Variants

| Appearance             | Use for                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `appearance="solid"`   | A sticker: a count or a mark that waits for the person, with an ink edge and ink type. The unread count and the @ marker |
| `appearance="soft"`    | A soft-tinted label with no border: status chips of agent states, the runtime chip                                       |
| `appearance="outline"` | A hairline label in Space Mono: the `agent` tag, a reply count beside a task chip                                        |

`variant` picks the color role. Choose it by what the color means, not by how it looks ([Meanings of color](https://raft-design.botiverse.build/foundations/color.md#meanings-of-color)): on a count, `accent` is the pink of "to do" and `primary` the yellow of "you".

## States

- A Badge rendered as a button (`render={<button />}`) shows the medium tier on hover and press (`sticker-medium` on a colour badge), and the shared disabled look ([States](https://raft-design.botiverse.build/foundations/states.md)).
- The selected row never shows a count or an @ marker ([States](https://raft-design.botiverse.build/foundations/states.md#usage)).

## Content

- Write the number alone, in Space Mono. Above 99, write 99+.
- Don't write a count in the @ marker: it says only that someone mentioned the person.

## Accessibility

Badge renders a `<span>` and wraps no Base UI primitive.

- Give a count or an @ marker with no words next to it `role="img"` and an `aria-label` that says what it means: "3 unread", "Mentions you".
- Give a Badge rendered as a button an `aria-label` that names its action ("Open thread replies") when its text doesn't.

## Rules

- Show at most one badge per row, in the same column as the time.
- When a row has both unread messages and a mention, show only the @ marker.
- Use the gray number for a muted place, never the pink sticker: the person chose not to be called by it.
- Put only the attention dot on rail and tab bar icons and on the bell, never a number.

## API

### Badge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `appearance` | `"outline" \| "solid" \| "soft"` | `"solid"` |  |
| `variant` | `"primary" \| "accent" \| "warning" \| "danger" \| "default" \| "information" \| "muted" \| "success"` | `"default"` |  |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

## Changes

- 0.6.0 (Breaking Changes): **Props that no longer change anything are removed:** `Badge` `uppercase`; `Checkbox` `size`, `variant`, `color`; `Status` `pulse`, `attention` (status never animates); `Switch` / `SwitchThumb` `size`; `SidebarItem` `variant`; `SidebarItemCount` / `SidebarItemIndicator` `variant` and `appearance` (the count is always the pink sticker, the indicator the yellow @); `NotificationCenterActionButton` `variant`; `DrawerContent` `width` (one-go forms use the wide `Dialog`); `AppRailItemIndicator` `attention`; `AppRailItemAttention` `children`; `Steps` `size`, `track`, `renderIndicator`, `renderTraveler`; `FilePreviewBadge` `type`, `color`. Remove them at call sites.
- 0.5.39 (Fixed): Brutal `TaskStatusBadge` draws a 1px black keyline instead of 2px, matching `TaskChip` and `Badge`; `py-px` keeps it exactly 20px tall, so surrounding layout does not move (Elegant unchanged).
- 0.5.31 (Fixed): `TaskStatusBadge` in Brutal is a square, hard-edged tag again (no radius, 2px black border, bold, 20px tall), matching the Brutal `TaskChip` and `Badge`. 0.5.30 rendered it as a rounded pill. Elegant is unchanged.