A compact status indicator that always pairs its color with a visible label.
import { StatusDot } from "@/components/ballmac/status-dot"
export default function StatusDotDemo() {
return (
<div className="bg-card flex w-full max-w-xs items-center justify-between rounded-xl border border-border px-4 py-3">
<span className="text-sm font-medium">Workspace sync</span>
<StatusDot label="All systems online" status="online" pulse />
</div>
)
}Installation
$ pnpm dlx shadcn@latest add @ballmac/status-dotCopy the source into your project.
components/ballmac/status-dot.tsx// Ballmac UI: Status Dot. https://ui.ballmac.com/components/status-dot import * as React from "react" import { cn } from "@/lib/utils" type StatusDotProps = React.ComponentProps<"span"> & { /** Visible status text; color is never the only cue. */ label: string /** Semantic status tone. */ status?: "online" | "busy" | "away" | "offline" /** Gently pulse active statuses; stops for reduced motion. */ pulse?: boolean /** Announce a changed status to assistive technology. */ announce?: boolean } function StatusDot({ className, label, status = "online", pulse = false, announce = false, ...props }: StatusDotProps) { return ( <span data-slot="status-dot" role={announce ? "status" : undefined} className={cn( "text-foreground inline-flex min-w-0 items-center gap-2 text-sm", className, )} {...props} > <span aria-hidden="true" className={cn( "relative size-2.5 shrink-0 rounded-full", status === "online" && "bg-chart-2", status === "busy" && "bg-destructive", status === "away" && "bg-chart-3", status === "offline" && "bg-muted-foreground", pulse && status !== "offline" && "after:absolute after:inset-0 after:animate-ping after:rounded-full after:bg-inherit after:opacity-20 motion-reduce:after:animate-none", )} /> <span className="truncate">{label}</span> </span> ) } export { StatusDot, type StatusDotProps }Update the import paths to match your project setup.
Usage
import { StatusDot } from "@/components/ballmac/status-dot"The full example is in the Code tab above.
Examples
States and variants
import { StatusDot } from "@/components/ballmac/status-dot"
export default function StatusDotStates() {
return (
<div className="bg-card grid w-full max-w-xs gap-3 rounded-xl border border-border p-4">
<StatusDot label="Available" status="online" />
<StatusDot label="In a meeting" status="busy" />
<StatusDot label="Away" status="away" />
<StatusDot label="Offline" status="offline" />
</div>
)
}API reference
| Prop | Type | Default |
|---|---|---|
label*Visible status text; color is never the only cue. | string | — |
statusSemantic status tone. | "online" | "busy" | "away" | "offline" | "online" |
pulseGently pulse active statuses; stops for reduced motion. | boolean | false |
announceAnnounce a changed status to assistive technology. | boolean | false |
Also accepts the standard attributes of its root element.
Accessibility
| Key | Action |
|---|---|
| None | Status is expressed in visible text |
Use with AI
A compact status indicator that always pairs its color with a visible label. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Status Dot (@ballmac/status-dot) to this project with the shadcn MCP, then use it where it fits.
Use it for
- Show presence or service state
- Label a live operational status
Not for
- Use badge for category labels
Registry JSON: https://ui.ballmac.com/r/status-dot.json
Credits
Free to use in personal and commercial projects.
- npm
- None
- Registry
- shadcn/utils
Pairs well with
Badge
A small pill label in four variants with an optional status dot and success, warning and error tones. Style links with badgeVariants().
Avatar
A Radix avatar with image and initials fallback, three sizes, an optional presence dot, and AvatarGroup for overlapping stacks with a +N overflow counter.
Alert Dialog
Focus-managed confirmation for consequential actions, with a clear cancel path, optional media, and a token-based destructive action.
Alert
A semantic callout with five theme-aware tones, clear icon placement, an action row, and opt-in urgent announcements.