Dot Group

A positioning container that pins indicator dots to the corners of content elements, with optional overflow handling and standalone stacking mode.

Open in

Loading component...

Installation

Usage

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

{/* Position dots on content */}
<DotGroup content={<Badge variant="neutral-inverted">kafka</Badge>} size="sm">
  <StatusDot variant="error" />
  <StatusDot variant="warning" />
</DotGroup>

{/* Standalone stacking (no content) */}
<DotGroup size="sm">
  <StatusDot variant="error" />
  <StatusDot variant="warning" />
</DotGroup>

When to use

Use DotGroup when:

Positioning indicator dots on a badge, avatar, or other content element
Displaying multiple status or count indicators that need compact stacking
You need to truncate many indicators to a visible subset (maxVisible prop)

Don't use DotGroup when:

You only have a single indicator without content to attach it to (use StatusDot or CountDot directly)
You need a label alongside the indicator (use StatusBadge)
On a StatusBadge — it already composes StatusDot internally

Modes

Content positioning mode

When content is provided, DotGroup wraps the content in a relative container and positions the dots at the specified corner. This is the primary use case.

<DotGroup content={<Badge variant="neutral-inverted">Service</Badge>} size="sm">
  <StatusDot variant="error" />
</DotGroup>

Standalone mode

Without content, DotGroup renders dots in a horizontal stack with overlapping negative margins. This is useful for inline indicator groups.

<DotGroup size="sm">
  <StatusDot variant="error" />
  <StatusDot variant="warning" />
</DotGroup>

Pattern: Same-type grouping

DotGroup is designed for same-type indicators only. Never mix StatusDot and CountDot in the same group. This ensures consistent sizing and visual weight.

// StatusDot group
<DotGroup content={<Badge variant="neutral-inverted">kafka</Badge>} size="sm">
  <StatusDot variant="error" />
  <StatusDot variant="warning" />
</DotGroup>

// CountDot group
<DotGroup content={<Badge variant="neutral-inverted">broker-0</Badge>} size="sm">
  <CountDot count={5} variant="warning" />
  <CountDot count={2} variant="error" />
</DotGroup>

Pattern: Overflow

When maxVisible is set and children exceed it, DotGroup renders the first N dots followed by a + icon signaling that more indicators exist. The icon sizes and contrasts automatically with the dots.

<DotGroup content={<Badge variant="neutral-inverted">events</Badge>} maxVisible={3} size="sm">
  <StatusDot variant="error" />
  <StatusDot variant="warning" />
  <StatusDot variant="info" />
  <StatusDot variant="success" />
  <StatusDot variant="disabled" />
</DotGroup>
{/* Shows the first 3 dots + overflow indicator */}

Anatomy

Content positioning mode
┌──────────────────────────────────┐
│                        [●][●]   │  ← absolute positioned at corner
│  Badge Label                    │
│                                 │
└──────────────────────────────────┘

Standalone mode
[●][●][●]  ← overlapping inline indicators with ring separation

API Reference

`DotGroup`

Prop	Type	Default	Description
`content`	`ReactNode?`	—	Element to position dots relative to
`position`	`"top-right" \| "top-left" \| "bottom-right" \| "bottom-left" \| "top" \| "bottom" \| "left" \| "right"`	`"top-right"`	Position for dots when using content mode (corners or edge-centers)
`size`	`"xxs" \| "xs" \| "sm" \| "md" \| "lg"`	`"md"`	Controls dot overlap spacing
`maxVisible`	`number?`	—	Maximum dots to show; overflow renders a `+` icon
`testId`	`string?`	—	Test ID for visual regression testing
`className`	`string?`	—	Additional CSS classes

Credits

Follows the overlapping stack pattern from AvatarGroup but simplified for indicator use cases.
Designed to compose with StatusDot and CountDot.