---
title: Badge
description: Compact status indicators and labels with semantic color variants.
icon: tag
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

Badges are small, pill-shaped labels for status indicators, counts, and categories. They're inline elements that sit naturally alongside text or within cards.

## Basic Usage

<ComponentPreview json={{"view":{"type":"Badge","label":"Mostly Harmless","variant":"default"}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQmFkZ2UKCkJhZGdlKCJNb3N0bHkgSGFybWxlc3MiKQo">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Badge

Badge("Mostly Harmless")
```
```json Protocol icon="brackets-curly"
{"view": {"type": "Badge", "label": "Mostly Harmless", "variant": "default"}}
```
</CodeGroup>
</ComponentPreview>

## Variants

Eight variants cover the most common use cases — five base styles from shadcn plus three semantic colors for status indicators.

<ComponentPreview json={{"view":{"cssClass":"gap-8 grid-cols-4 place-items-center","type":"Grid","children":[{"type":"Badge","label":"Default","variant":"default"},{"type":"Badge","label":"Secondary","variant":"secondary"},{"type":"Badge","label":"Destructive","variant":"destructive"},{"type":"Badge","label":"Outline","variant":"outline"},{"type":"Badge","label":"Ghost","variant":"ghost"},{"type":"Badge","label":"Success","variant":"success"},{"type":"Badge","label":"Warning","variant":"warning"},{"type":"Badge","label":"Info","variant":"info"}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Badge, Grid

with Grid(gap=8, columns=4, css_class="place-items-center"):
    Badge("Default")
    Badge("Secondary", variant="secondary")
    Badge("Destructive", variant="destructive")
    Badge("Outline", variant="outline")
    Badge("Ghost", variant="ghost")
    Badge("Success", variant="success")
    Badge("Warning", variant="warning")
    Badge("Info", variant="info")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-8 grid-cols-4 place-items-center",
    "type": "Grid",
    "children": [
      {"type": "Badge", "label": "Default", "variant": "default"},
      {"type": "Badge", "label": "Secondary", "variant": "secondary"},
      {"type": "Badge", "label": "Destructive", "variant": "destructive"},
      {"type": "Badge", "label": "Outline", "variant": "outline"},
      {"type": "Badge", "label": "Ghost", "variant": "ghost"},
      {"type": "Badge", "label": "Success", "variant": "success"},
      {"type": "Badge", "label": "Warning", "variant": "warning"},
      {"type": "Badge", "label": "Info", "variant": "info"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Examples

Badges pair well with cards and other layout components as inline status indicators.

<ComponentPreview json={{"view":{"cssClass":"gap-3","type":"Column","children":[{"type":"Card","children":[{"type":"CardHeader","children":[{"cssClass":"gap-2 items-center","type":"Row","children":[{"type":"CardTitle","content":"Heart of Gold"},{"type":"Badge","label":"Online","variant":"success"}]},{"type":"CardDescription","content":"Infinite Improbability Drive engaged"}]}]},{"type":"Card","children":[{"type":"CardHeader","children":[{"cssClass":"gap-2 items-center","type":"Row","children":[{"type":"CardTitle","content":"Vogon Fleet"},{"type":"Badge","label":"Approaching","variant":"warning"}]},{"type":"CardDescription","content":"Demolition order filed with local planning authority"}]}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Badge,
    Card,
    CardDescription,
    CardHeader,
    CardTitle,
    Column,
    Row,
)

with Column(gap=3):
    with Card():
        with CardHeader():
            with Row(gap=2, css_class="items-center"):
                CardTitle("Heart of Gold")
                Badge("Online", variant="success")
            CardDescription("Infinite Improbability Drive engaged")
    with Card():
        with CardHeader():
            with Row(gap=2, css_class="items-center"):
                CardTitle("Vogon Fleet")
                Badge("Approaching", variant="warning")
            CardDescription("Demolition order filed with local planning authority")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-3",
    "type": "Column",
    "children": [
      {
        "type": "Card",
        "children": [
          {
            "type": "CardHeader",
            "children": [
              {
                "cssClass": "gap-2 items-center",
                "type": "Row",
                "children": [
                  {"type": "CardTitle", "content": "Heart of Gold"},
                  {"type": "Badge", "label": "Online", "variant": "success"}
                ]
              },
              {"type": "CardDescription", "content": "Infinite Improbability Drive engaged"}
            ]
          }
        ]
      },
      {
        "type": "Card",
        "children": [
          {
            "type": "CardHeader",
            "children": [
              {
                "cssClass": "gap-2 items-center",
                "type": "Row",
                "children": [
                  {"type": "CardTitle", "content": "Vogon Fleet"},
                  {"type": "Badge", "label": "Approaching", "variant": "warning"}
                ]
              },
              {
                "type": "CardDescription",
                "content": "Demolition order filed with local planning authority"
              }
            ]
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

Badge is a container component, so you can compose children for richer content — icons, loaders, or custom ordering.

<ComponentPreview json={{"view":{"cssClass":"gap-4 items-center","type":"Row","children":[{"type":"Badge","variant":"success","children":[{"type":"Icon","name":"check","size":"sm"},{"content":"Verified","type":"Text"}]},{"type":"Badge","variant":"default","children":[{"type":"Loader","variant":"spin","size":"sm"},{"content":"Syncing","type":"Text"}]},{"type":"Badge","variant":"secondary","children":[{"type":"Loader","variant":"dots","size":"sm"},{"content":"Processing","type":"Text"}]}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQmFkZ2UsIEljb24sIExvYWRlciwgUm93LCBUZXh0Cgp3aXRoIFJvdyhnYXA9NCwgY3NzX2NsYXNzPSJpdGVtcy1jZW50ZXIiKToKICAgIHdpdGggQmFkZ2UodmFyaWFudD0ic3VjY2VzcyIpOgogICAgICAgIEljb24oImNoZWNrIiwgc2l6ZT0ic20iKQogICAgICAgIFRleHQoIlZlcmlmaWVkIikKICAgIHdpdGggQmFkZ2UoKToKICAgICAgICBMb2FkZXIoc2l6ZT0ic20iKQogICAgICAgIFRleHQoIlN5bmNpbmciKQogICAgd2l0aCBCYWRnZSh2YXJpYW50PSJzZWNvbmRhcnkiKToKICAgICAgICBMb2FkZXIodmFyaWFudD0iZG90cyIsIHNpemU9InNtIikKICAgICAgICBUZXh0KCJQcm9jZXNzaW5nIikK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Badge, Icon, Loader, Row, Text

with Row(gap=4, css_class="items-center"):
    with Badge(variant="success"):
        Icon("check", size="sm")
        Text("Verified")
    with Badge():
        Loader(size="sm")
        Text("Syncing")
    with Badge(variant="secondary"):
        Loader(variant="dots", size="sm")
        Text("Processing")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 items-center",
    "type": "Row",
    "children": [
      {
        "type": "Badge",
        "variant": "success",
        "children": [
          {"type": "Icon", "name": "check", "size": "sm"},
          {"content": "Verified", "type": "Text"}
        ]
      },
      {
        "type": "Badge",
        "variant": "default",
        "children": [
          {"type": "Loader", "variant": "spin", "size": "sm"},
          {"content": "Syncing", "type": "Text"}
        ]
      },
      {
        "type": "Badge",
        "variant": "secondary",
        "children": [
          {"type": "Loader", "variant": "dots", "size": "sm"},
          {"content": "Processing", "type": "Text"}
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Badge Parameters">
<ParamField body="label" type="str | None" default="None">
  Badge text. Can be passed as a positional argument. When using children, omit the label and compose content directly.
</ParamField>

<ParamField body="variant" type="str" default="default">
  Visual style: `"default"`, `"secondary"`, `"destructive"`, `"outline"`, `"ghost"`, `"success"`, `"warning"`, `"info"`.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes appended to the component's built-in styles.
</ParamField>
</Card>

## Protocol Reference

```json Badge
{
  "type": "Badge",
  "children?": "[Component]",
  "let?": "object",
  "label?": "string",
  "variant?": "default | secondary | destructive | success | warning | info | outline | ghost",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Badge](/protocol/badge).
