---
title: Count Dot
description: A numerical indicator dot for displaying counts with semantic color variants and optional stacked positioning.
icon: hash
author:
  name: eblairmckee
  url: https://github.com/eblairmckee
mode: wide
---

### Installation

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

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

## Usage

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

<CountDot count={5} variant="destructive" />

<CountDot count={150} max={99} variant="informative" />

{/* Positioned on content via DotGroup */}
<DotGroup content={<Badge tone="default" variant="subtle">Inbox</Badge>} size="sm" items={[
    {
        id: "errors",
        kind: "count",
        count: 3,
        variant: "destructive"
    }
]}/>
```

## When to use

**Use CountDot when:**

- Showing unread message or notification counts
- Indicating the number of items requiring attention
- Displaying a count badge on icons, avatars, or badges

**Don't use CountDot when:**

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

## Behavior

- Returns `null` when `count <= 0` — nothing renders
- When `count > max`, displays `"{max}+"` (e.g., `99+`)
- Default `max` is `99`

## Anatomy

```
CountDot
┌───────┐
│  42   │  ← rounded pill with count text
└───────┘

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

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

```tsx
<DotGroup
  content={
    <Badge tone="default" variant="subtle">
      Alerts
    </Badge>
  }
  size="sm"
  items={[
    {
      id: 'warnings',
      kind: 'count',
      count: 42,
      variant: 'warning',
    },
  ]}
/>
```

## API Reference

### `CountDot`

| Prop        | Type                                                        | Default  | Description                                                     |
| ----------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `count`     | `number`                                                    | —        | The number to display (required)                                |
| `max`       | `number`                                                    | `99`     | Maximum count before showing overflow (e.g., `99+`)             |
| `variant`   | `"success" \| "info" \| "warning" \| "error" \| "disabled"` | `"info"` | Dot color variant                                               |
| `size`      | `"sm" \| "md" \| "lg"`                                      | `"md"`   | Indicator size                                                  |
| `stacked`   | `boolean`                                                   | `false`  | Adds border ring for overlapping contexts (managed by DotGroup) |
| `testId`    | `string?`                                                   | —        | Test ID for visual regression testing                           |
| `className` | `string?`                                                   | —        | Additional CSS classes                                          |

## Credits

- Shares the same semantic color variants as [StatusDot](/docs/status-dot) for a consistent indicator system.