---
title: StatusBadge
description: A badge that shows a state with a tone, an icon, and text.
category: Basic
status: beta
since: 0.3.4
tags: [badge, status, signal]
syncStatus: reviewed
verified: true
---

## Usage

### Status Signals
`status` sets the tone; `muted` renders an empty dashed ring with no glyph.
:::TuffDemoWrapper{demo="StatusBadgeSignalsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxStatusBadge text="Approved" status="success" />
    <TxStatusBadge text="Pending" status="warning" />
    <TxStatusBadge text="Cancelled" status="danger" />
    <TxStatusBadge text="In Review" status="info" />
    <TxStatusBadge text="Not started" status="muted" />
  </template>
---
:::

### Dashboard Operations Status
Works with `TxStatCard` and `TxProgressBar` to summarize release, build, and sync health.
:::TuffDemoWrapper{demo="ComponentsOperationsStatusDemo" code-lang="vue"}
---
code: |
  <template>
    <TxStatusBadge text="Review done" status="success" size="sm" />
    <TxStatusBadge text="Build stable" status="success" os="linux" size="sm" />
    <TxStatusBadge text="Sync healthy" status-key="granted" size="sm" />

    <TxStatCard variant="progress" value="99.9%" label="API availability" meta="Normal" :progress="99" icon-class="i-carbon-cloud-monitoring" />
    <TxStatCard variant="progress" :value="18" label="Pending queue" meta="Watch" :progress="64" icon-class="i-carbon-queued" />
  </template>
---
:::

### Status Row
:::TuffDemoWrapper{demo="StatusBadgeRowDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar name="TA" />
    <TxStatusBadge text="Online" status="success" />
  </template>
---
:::

### Best Practices

- Use `statusKey` when the state comes from an API or permission enum; use `status` for page-local decisions.
- Don't rely on color alone; write complete labels such as “Sync healthy” or “Access denied”.
- Use `os` only when the platform changes what the state means.
- Put primary actions on a `TxButton` beside the badge; never make the badge the only control.

## API Reference

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | `string` | required | Visible label. |
| `icon` | `string` | `''` | Custom icon class that replaces the tone's default glyph. |
| `status` | `'success' \| 'warning' \| 'danger' \| 'info' \| 'muted'` | - | Explicit tone; takes precedence over `statusKey`. |
| `statusKey` | `'granted' \| 'denied' \| 'notDetermined' \| 'unsupported' \| string` | `''` | Permission or status key mapped to a tone. |
| `size` | `'sm' \| 'md'` | `'md'` | Badge density. |
| `os` | `'macos' \| 'windows' \| 'linux'` | - | Shows a platform icon before the status icon. |
| `osOnly` | `boolean` | `false` | Shows only the platform icon, hiding the status icon. |

### Events

| Event | Payload | Description |
|------|---------|-------------|
| `click` | `MouseEvent` | Fires on click, or on Enter / Space when the badge acts as a button. |

### CSS Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `--tx-status-chip-size` | `18px` (`sm`: `15px`) | Diameter of the status disc, which scales the glyph; set on the root by the `size` class. |

## Overview

- Without a click listener, the root is `role="status"`; with `@click`, it becomes a focusable `role="button"` that Enter / Space activate.
- `status` wins over `statusKey`, which maps `granted` → success, `denied` → danger, `notDetermined` → warning, `unsupported` → muted, and anything else to info.
- Default glyphs are solid, since the disc supplies the enclosing circle: success `i-carbon-checkmark`, warning `i-carbon-time`, danger `i-carbon-close`, info `i-carbon-information`.
- `muted` has no glyph and renders an empty dashed ring; passing `icon` restores the filled disc.
- `osOnly` hides the status icon but keeps the text.

## Technologies

- The disc uses a separate `--tx-status-chip-*` ramp, not `--tx-color-*`, so knocked-out glyphs stay at or above 3:1; high-contrast dark inverts it to a light disc with a dark glyph.
- The label is monospace, on a 14% status-color fill with a 32%, 1px inset ring that takes no layout space.
- Source: `packages/tuffex/packages/components/src/status-badge/`.

<TuffDocSourceLink />