Loading States

Loading States

Loading states should reduce uncertainty. Pick the least distracting treatment that tells the user the system is working.

Source: https://dotmatrix.zzzzshawn.cloud/

Choose the Right Pattern

| Wait type | Pattern | | --- | --- | | Under 500ms | optimistic UI or no loader | | 500ms to 2s | small spinner, dot loader, or inline status text | | 2s+ | skeleton, progress region, or staged status | | Known progress | progress bar with percent or steps | | Background refresh | quiet inline state; avoid blocking | | Empty data | empty state with one next action |

Dot Matrix

Use Dot Matrix when the product wants a compact, crafted loader. It is React, TypeScript, Tailwind, and shadcn-oriented.

Install one loader through the shadcn registry:

npx shadcn@latest add @dotmatrix/dotm-square-3

Use it for small pending states, buttons, command palettes, creative tools, or branded surfaces. Avoid using multiple animated loaders on the same screen.

Smooth Loader Rules

• Drive continuous opacity with requestAnimationFrame, not a coarse interval.
• Use smooth ramps (smoothstep style falloffs) instead of hard opacity thresholds.
• For path loaders, use a floating head position and a soft tail.
• Freeze or simplify animation for prefers-reduced-motion.
• Pause looping animation when off-screen.
• Keep loading motion calm in dense SaaS/admin interfaces.

Accessibility Rules

• Use aria-busy on regions that are updating.
• Use role="status" or visible status text for important pending states.
• Do not rely on animation alone to communicate progress.
• Skeletons should match the final layout closely enough to prevent layout shift.
• Button-level loaders must preserve the button size and accessible name.

Button Pending Pattern

  {isPending ?  : null}
  {isPending ? "Saving..." : "Save Changes"}

Keep the label specific. Prefer Saving... over generic Loading... when the action is known.

Preflight

Before shipping:

• The layout does not jump when loading begins or ends.
• Reduced motion has a stable fallback.
• The pending state cannot be mistaken for disabled without progress.
• The user has a path forward if loading fails or returns empty.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tommylower
• Source: tommylower/cortex
• License: MIT

Install and usage instructions live in the source repository linked above.