---
title: Status Badge
description: Displays a pulsing status indicator with a label, useful for showing the state of a process or service.
icon: circle-dot
author:
  name: eblairmckee
  url: https://github.com/eblairmckee
mode: wide
---

<PoweredBy packages={[{ name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/badge' }]} />

### Installation

```package-install
npx shadcn@latest add @redpanda/status-badge
```

<ComponentPreview name="status-badge-demo" />

## Usage

```tsx lineNumbers
import { StatusBadge } from "@/components/redpanda-ui/status-badge"

{/* Default label deduced from variant */}
<StatusBadge variant="success" />        {/* → "Running" */}
<StatusBadge variant="starting" />       {/* → "Starting" (spinner) */}
<StatusBadge variant="stopping" />       {/* → "Stopping" (spinner) */}

{/* Custom label overrides default */}
<StatusBadge variant="success">Healthy</StatusBadge>

{/* Enable pulsing when Mali says so */}
<StatusBadge variant="disabled" pulsing />
```

## When to use

```mermaid
graph TD;
    A[❓ Need to show process state?] --> B{What kind of status?};
    B --> C[✅ Service health / pipeline state];
    B --> D[⚠️ Static category or tag];

    C --> E[❓ Is the state active?];
    D --> F[⚠️ Use Badge instead];

    E --> G[✅ Use StatusBadge with pulsing];
    E --> H[✅ Use StatusBadge with pulsing=false];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;

    class C,G,H recommended;
    class D,F discouraged;
    class A,B,E decision;
```

**Use StatusBadge when:**

- Showing live process state (running, starting, stopping, error)
- Displaying service health (online, degraded, offline)
- Indicating connection or sync status

**Don't use StatusBadge when:**

- Displaying static categories or tags (use [Badge](/docs/badge))
- You only need the dot without a label (use [StatusDot](/docs/status-dot))
- Showing counts or notifications (use [CountDot](/docs/count-dot))
- The status is purely informational with no temporal aspect

## Anatomy

```
StatusBadge (static state)
┌────────────────────────────────────────┐
│  ┌────────────┐                        │
│  │  StatusDot  │      Label Text       │
│  │  ◉ (pulse) │                        │
│  └────────────┘                        │
└────────────────────────────────────────┘

StatusBadge (transitioning state)
┌────────────────────────────────────────┐
│  ┌────────────┐                        │
│  │  Spinner ↻  │      Label Text       │
│  │             │                        │
│  └────────────┘                        │
└────────────────────────────────────────┘
```

**Component Structure:**

1. **StatusBadge** (Root): Wraps Badge with an indicator icon
2. **StatusDot**: Animated colored dot for static states (`success`, `informative`, `warning`, `destructive`, `disabled`)
3. **Spinner**: Animated loading spinner for transitioning states (`starting`, `stopping`)

> **Note:** StatusBadge composes StatusDot internally — do not wrap StatusBadge in [DotGroup](/docs/dot-group) or add dot components to it.

## API Reference

### `StatusBadge`

| Prop        | Type                                                                                    | Default              | Description                                                       |
| ----------- | --------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |
| `variant`   | `"success" \| "info" \| "warning" \| "error" \| "disabled" \| "starting" \| "stopping"` | `"info"`             | Status variant; `starting`/`stopping` show a spinner              |
| `pulsing`   | `boolean`                                                                               | `false`              | Whether the indicator dot animates (ignored for spinner variants) |
| `size`      | `"sm" \| "md" \| "lg"`                                                                  | `"md"`               | Badge and indicator size                                          |
| `children`  | `ReactNode?`                                                                            | Deduced from variant | Label text; defaults to variant name (see table below)            |
| `testId`    | `string?`                                                                               | —                    | Test ID for visual regression testing                             |
| `className` | `string?`                                                                               | —                    | Additional CSS classes                                            |

### Default labels

When no `children` are provided, the label is deduced from the variant:

| Variant       | Default Label | Indicator |
| ------------- | ------------- | --------- |
| `success`     | Running       | StatusDot |
| `informative` | Pending       | StatusDot |
| `warning`     | Warning       | StatusDot |
| `destructive` | Error         | StatusDot |
| `disabled`    | Stopped       | StatusDot |
| `starting`    | Starting      | Spinner   |
| `stopping`    | Stopping      | Spinner   |

## Related

- [StatusDot](/docs/status-dot) — Standalone animated status indicator dot
- [CountDot](/docs/count-dot) — Numerical count indicator dot
- [Badge](/docs/badge) — Base badge component

## Credits

- Inspired by the [Kibo UI Status](https://www.kibo-ui.com/components/status) component for the pulsing indicator pattern and variant design.
- Built on top of the [Badge](/docs/badge) component for consistent sizing and styling.