# DotLoader

> Slug: `dot-loader` · Category: Feedback

## When to use
- Indeterminate loading affordance for short-lived async work — submitting a form, loading a panel, fetching data.
- Inline indicators inside cards, modals, or buttons-replaced-by-spinners patterns.

## When NOT to use
- Determinate progress (you know the percentage) -> `ProgressBar` or `ProgressRing`.
- Page-level skeletons -> custom skeleton placeholders.
- Loading button state -> set `loading` on `Button` (it has its own announcement).

## Variants & decision tree
- Compact inline use (small surfaces, tight rows) -> `size="small"`.
- Centerpiece / page-load state -> `size="large"`.
- Brand color -> `variant="branded"` (default). Neutral surfaces -> `variant="monochrome"`.

## States
- `inverse` — dark-background styling.
- Animation is always running while mounted; unmount when work finishes.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`size`** | `'small' \| 'large'` | — | Visual size. |
| `variant` | `'branded' \| 'monochrome'` | `'branded'` | Coloring variant. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `a11yLabel` | `string` | `'Loading'` | Screen-reader announcement. |
| `className` | `string` | — | Additional class names. |

The component also accepts standard `HTMLAttributes<HTMLDivElement>`.

## Usage examples
```tsx
import { DotLoader } from 'arrow-react-bootstrap';

// Small inline loader inside a card
{loading && <DotLoader size="small" a11yLabel="Loading account details" />}

// Page-level loading state
<div className="tdds:d-flex tdds:jc-center tdds:pt-6">
  <DotLoader size="large" />
</div>
```

## Composition
- Use as a placeholder while data fetches; replace with content when ready.
- Inside a `Modal` body during async submit, render the loader and disable controls.

## Accessibility
- Provide a meaningful `a11yLabel` — Arrow exposes it via a screen-reader-only span.
- Mount only when actually loading, and unmount when done — that signals "loading complete" to AT.

## Do / Don't
- Do: use this for short loads (≤ a few seconds). For longer waits, use `ProgressBar`.
- Do: localize `a11yLabel` for non-English contexts.
- Don't: leave a `DotLoader` mounted indefinitely as an empty-state placeholder.
- Don't: stack multiple sibling loaders — one per logical region is enough.
