---
title: Status Dot
description: A standalone animated status indicator dot with semantic color variants and optional stacked positioning.
icon: circle
author:
  name: eblairmckee
  url: https://github.com/eblairmckee
mode: wide
---

<PoweredBy packages={[{ name: 'Kibo UI', url: 'https://www.kibo-ui.com/components/status' }]} />

### Installation

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

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

## Usage

```tsx lineNumbers
import { StatusDot } from "@/components/redpanda-ui/status-dot"
import { DotGroup } from "@/components/redpanda-ui/dot-group"
import { Badge } from "@/components/redpanda-ui/badge"

<StatusDot variant="success" />

<StatusDot variant="destructive" />

{/* Positioned on content via DotGroup */}
<DotGroup content={<Badge tone="default" variant="subtle">Service</Badge>} size="sm" items={[
    {
        id: "healthy",
        kind: "status",
        variant: "success"
    }
]}/>
```

## When to use

**Use StatusDot when:**

- Showing live status inline next to text or labels
- Indicating connection or health state on a badge or avatar
- Building custom status indicators with composition

**Don't use StatusDot when:**

- You need a label alongside the dot (use [StatusBadge](/docs/status-badge))
- Showing numerical counts (use [CountDot](/docs/count-dot))
- On a [StatusBadge](/docs/status-badge) — it already includes a StatusDot internally

## Anatomy

```
StatusDot
┌───────────────┐
│  ● ping ring  │  ← animated pulse (when pulsing=true)
│  ● solid dot  │  ← inner colored dot
└───────────────┘

Positioned on Badge (via DotGroup)
┌─────────────────────┐
│  Badge Label    [●]─┤  ← positioned at corner with border ring
└─────────────────────┘
```

**Positioning pattern:**
Use [DotGroup](/docs/dot-group) with the `content` prop to position StatusDot on badges, avatars, or other elements.

```tsx
<DotGroup
  content={
    <Badge tone="default" variant="subtle">
      Messages
    </Badge>
  }
  size="sm"
  items={[
    {
      id: 'healthy',
      kind: 'status',
      variant: 'success',
    },
  ]}
/>
```

## API Reference

### `StatusDot`

| Prop        | Type                                                        | Default  | Description                                                     |
| ----------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `variant`   | `"success" \| "info" \| "warning" \| "error" \| "disabled"` | `"info"` | Dot color variant                                               |
| `pulsing`   | `boolean`                                                   | `false`  | Whether the dot has a ping animation                            |
| `size`      | `"xxs" \| "xs" \| "sm" \| "md" \| "lg"`                     | `"md"`   | Indicator size                                                  |
| `stacked`   | `boolean`                                                   | `false`  | Adds border ring for overlapping contexts (managed by DotGroup) |
| `children`  | `ReactNode?`                                                | —        | Content rendered inside the inner dot                           |
| `testId`    | `string?`                                                   | —        | Test ID for visual regression testing                           |
| `className` | `string?`                                                   | —        | Additional CSS classes                                          |

## Credits

- Extracted from the [StatusBadge](/docs/status-badge) component for standalone use.
- Inspired by the [Kibo UI Status](https://www.kibo-ui.com/components/status) component for the pulsing indicator pattern.