Loading Dots

A compact loading status with staggered token-colored dots that stop for reduced motion.

Preparing your workspace

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-dots

Add the Ballmac items it builds on.
```
$ pnpm dlx shadcn@latest add @ballmac/i18n
```

Copy 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

Open in

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
`label` Status text available to screen readers.	string	—
`size` Dot size.	"sm" \| "default" \| "lg"	"default"

Also accepts the standard attributes of its root element.

Accessibility

Key	Action
None	Accessible status label

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/i18n shadcn/utils

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.