A compact loading status with staggered token-colored dots that stop for reduced motion.
import { LoadingDots } from "@/components/ballmac/loading-dots"
export default function LoadingDotsDemo() {
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">Preparing your workspace</span>
<LoadingDots label="Preparing workspace" />
</div>
)
}Installation
$ pnpm dlx shadcn@latest add @ballmac/loading-dotsAdd the Ballmac items it builds on.
$ pnpm dlx shadcn@latest add @ballmac/i18nCopy the source into your project.
components/ballmac/loading-dots.tsx// Ballmac UI: Loading Dots. https://ui.ballmac.com/components/loading-dots "use client" import * as React from "react" import { cn } from "@/lib/utils" import { useMessages } from "@/lib/ballmac/i18n" type LoadingDotsProps = React.ComponentProps<"span"> & { /** Status text available to screen readers. */ label?: string /** Dot size. */ size?: "sm" | "default" | "lg" } function LoadingDots({ className, label, size = "default", ...props }: LoadingDotsProps) { const msg = useMessages() label ??= msg("loading-dots.label", "Loading") return ( <span data-slot="loading-dots" role="status" aria-label={label} className={cn("text-primary inline-flex items-center gap-1", className)} {...props} > {[0, 1, 2].map((index) => ( <span key={index} aria-hidden="true" className={cn( "rounded-full bg-current motion-safe:animate-bounce", size === "sm" && "size-1", size === "default" && "size-1.5", size === "lg" && "size-2", )} style={{ animationDelay: `${index * 120}ms` }} /> ))} </span> ) } export { LoadingDots, type LoadingDotsProps }Update the import paths to match your project setup.
Usage
import { LoadingDots } from "@/components/ballmac/loading-dots"The full example is in the Code tab above.
Examples
States and variants
import { LoadingDots } from "@/components/ballmac/loading-dots"
export default function LoadingDotsStates() {
return (
<div className="bg-card flex w-full max-w-xs items-end justify-around rounded-xl border border-border p-5">
<LoadingDots size="sm" label="Loading small example" />
<LoadingDots label="Loading standard example" />
<LoadingDots size="lg" label="Loading large example" />
</div>
)
}API reference
| Prop | Type | Default |
|---|---|---|
labelStatus text available to screen readers. | string | — |
sizeDot size. | "sm" | "default" | "lg" | "default" |
Also accepts the standard attributes of its root element.
Accessibility
| Key | Action |
|---|---|
| None | Accessible status label |
Quality scorecard
Every applicable check passes
Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.
Passed: Accessibility scan
No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).
Passed: Small screens
No sideways scrolling at 360, 390 or 1280 px wide.
Passed: Reduced motion
Every endless animation stops when the visitor asks for less motion.
Passed: Right to left
Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).
Passed: Clean console
No console errors or React hydration errors while loading.
Not applicable: Keyboard
Static content: nothing to focus.
Not applicable: Loading, empty and error
Does not show data or take submissions.
For information: Automated tests
No test file of its own yet.
For information: Footprint
0.6 KB of source (gzip) in 1 file. No extra npm packages.
Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.
Use with AI
A compact loading status with staggered token-colored dots that stop for reduced motion. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Loading Dots (@ballmac/loading-dots) to this project with the shadcn MCP, then use it where it fits.
Use it for
- Indicate short pending work
- Pair a compact loader with a button label
Not for
- Use skeleton for a full content placeholder
Registry JSON: https://ui.ballmac.com/r/loading-dots.json
Credits
Free to use in personal and commercial projects.
- npm
- None
- Registry
- @ballmac/i18nshadcn/utils
Pairs well with
Spinner
A compact loading indicator with three sizes, an accessible label, and reduced-motion behavior.
Button
A button with six variants, three sizes, a pill shape and a built-in loading state. buttonVariants() styles links the same way.
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.
Ballmac UI Pro
Need the whole screen, not one piece?
311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.
Not ready? Try three Pro blocks free
Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.