---
title: "Badge"
description: "A small pill used to label status, counts or categories."
---

A small pill for a count, a state or a label. The `dot` variant puts a filled circle before the text, which is how a status reads at a glance without relying on the pill's colour alone.

_Live example of Badge — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add badge
```

npm dependencies: class-variance-authority.

Files written — React: components/ui/badge.tsx. Vue: components/ui/badge/Badge.vue, components/ui/badge/index.ts.

## Usage

React:

```tsx
import { Badge } from "@/components/ui/badge"
```

Vue:

```ts
import { Badge } from "@/components/ui/badge"
```

## API reference

**`Badge`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "brand" \| "success" \| "warning" \| "danger"` | `"default"` | What the badge is reporting. |
| `dot` | `boolean` | `false` | Renders a leading dot in the current text colour. |

Every part also accepts the native attributes of the element it renders, and a `className` that is merged rather than replaced.

## Accessibility

A badge is text, not a control. If it reports something that changes — an unread count, a build status — put it in a container with `aria-live="polite"` so the change is announced. Never let the colour be the only difference between two states: the words in the badge should differ too.

## Tokens

Badge reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.