Data Display

Status Dot

Server Component

Presence dot with pulse, optional label, and avatar-overlay anchoring.

Import

tsx

import { StatusDot } from "@cronus-ui/ui";

bash

npx cronus-ui add status-dot

Examples

Statuses

Presence dots across the semantic palette. `withLabel` renders the status text next to the dot; without it the label becomes the accessible name.

OnlineAwayBusyOfflineDeploying

tsx

<div className="flex flex-wrap items-center gap-x-6 gap-y-3">
  <StatusDot status="online" withLabel />
  <StatusDot status="away" withLabel />
  <StatusDot status="busy" withLabel />
  <StatusDot status="offline" withLabel />
  <StatusDot status="info" withLabel label="Deploying" />
</div>

On an avatar

Anchor the dot to a corner with `position` and add `ring` so it cuts out of the image. Wrap the avatar and the dot in a `relative` container.

CNALJL

tsx

function StatusDotAvatarDemo() {
  return (
    <div className="flex items-center gap-6">
      <span className="relative inline-flex">
        <Avatar>
          <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
          <AvatarFallback>CN</AvatarFallback>
        </Avatar>
        <StatusDot status="online" position="bottom-right" ring aria-label="@shadcn is online" />
      </span>
      <span className="relative inline-flex">
        <Avatar>
          <AvatarFallback>AL</AvatarFallback>
        </Avatar>
        <StatusDot status="busy" position="bottom-right" ring aria-label="Ada is busy" />
      </span>
      <span className="relative inline-flex">
        <Avatar>
          <AvatarFallback>JL</AvatarFallback>
        </Avatar>
        <StatusDot status="offline" position="bottom-right" ring aria-label="Jean is offline" />
      </span>
    </div>
  );
}

Pulse & sizes

`pulse` adds an expanding ping halo for live activity — it stays static under `prefers-reduced-motion`. Sizes run `xs` through `lg`.

LiveStreaming

tsx

<div className="flex flex-col items-center gap-5">
  <div className="flex items-center gap-6">
    <StatusDot status="error" pulse withLabel label="Live" />
    <StatusDot status="success" pulse withLabel label="Streaming" />
  </div>
  <div className="flex items-center gap-4">
    <StatusDot size="xs" aria-label="Online (xs)" />
    <StatusDot size="sm" aria-label="Online (sm)" />
    <StatusDot size="md" aria-label="Online (md)" />
    <StatusDot size="lg" aria-label="Online (lg)" />
  </div>
</div>

API Reference

Generated from the component's exported types.

StatusDotProps

Extends Omit<HTMLAttributes<HTMLSpanElement>, "children">, VariantProps<typeof statusDotVariants>

Prop	Type	Default	Description
`status`	`StatusDotStatus`	`"online"`	Presence / semantic state the dot communicates. Drives the fill color and the default accessible name.
`size`	`StatusDotSize`	`"md"`	Dot size preset.
`ring`	`boolean`	`false`	Draws a surface-colored ring around the dot so it cuts out cleanly when overlaid on an avatar or icon.
`label`	`string`	The English name of `status` (e.g. `"Online"`).	Status text. Rendered next to the dot when `withLabel` is set; otherwise rendered as visually-hidden live-region content so screen readers announce both the initial status and later `status` changes.
`withLabel`	`boolean`	`false`	Renders `label` visibly next to the dot (in `text-fg-secondary`) instead of exposing it only to assistive technology.
`pulse`	`boolean`	`false`	Animates an expanding "ping" halo behind the dot to draw attention. The halo reuses the dot's fill; the hollow `offline` dot gets a matching outline halo instead (its fill is transparent). The animation only runs for users who have not requested reduced motion.
`position`	`StatusDotPosition`	`"none"`	Absolute corner anchor for overlaying the dot on an avatar or icon — place the component inside a `relative` wrapper. The "right" corners map to the inline end, so they mirror under RTL.