# LoadingDots

Shows three pulsing dots for inline loading.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/LoadingDots.tsx)

## Overview

LoadingDots renders three pulsing dots inline, such as inside a button or beside text.

## Examples

### Basic

```tsx
import { LoadingDots } from '@tempoxyz/ds'

export function Demo() {
  return <LoadingDots />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/LoadingDots/Basic.tsx)

### Size

Set `size` to `small`, `medium` (default), or `large`.

```tsx
import { LoadingDots, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <LoadingDots key={size} size={size} />
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '24' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/LoadingDots/Size.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { LoadingDots } from '@tempoxyz/ds'

<LoadingDots />
```

## Guidelines

### When to Use

* Show a short wait inside a line of text, such as Estimating network fee.
* Hold the place of one inline value, such as an exchange rate or a recipient name.

### When Not to Use

* Use `loading` on a [Button](/docs/components/button) while its action runs.
* Use [Spinner](/docs/components/spinner) for a busy region or control.
* Use [Skeleton](/docs/components/skeleton) for content with a known shape, such as rows or cards.
* Use [Progress](/docs/components/progress) for measurable work, or any wait longer than about 10 seconds.

### Keep Them in Line With Text

The dots render as an inline `span`, aligned to the middle of the line in the current text color.

**Do:** Put the dots after the words that describe the wait.

```tsx
/**
 * Do example for "Keep Them in Line With Text" on the LoadingDots page.
 * Put the dots after the words that describe the wait.
 * @module
 */
import { LoadingDots, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.text()}>
      Estimating network fee <LoadingDots aria-label="Estimating network fee" size="small" />
    </div>
  )
}

namespace styles {
  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
}
```

**Don't:** Fill an empty card with dots in place of its content.

```tsx
/**
 * Don't example for "Keep Them in Line With Text" on the LoadingDots page.
 * Don't fill an empty card with dots in place of its content.
 * @module
 */
import { LoadingDots, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <div {...styles.title()}>Activity</div>
      <div {...styles.body()}>
        <LoadingDots size="large" />
      </div>
    </div>
  )
}

namespace styles {
  export const body = style({
    alignItems: 'center',
    display: 'flex',
    height: '100',
    justifyContent: 'center',
  })

  export const card = style({
    borderColor: 'line.secondary',
    borderRadius: 'xs',
    borderStyle: 'solid',
    borderWidth: 'regular',
    boxSizing: 'border-box',
    padding: '16',
    width: '100% !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b2Strong' })
}
```

### Show Them Only After a Delay

* **Fast Responses (Under 300 ms):** Show no dots. Render the value when it arrives.
* **Longer Waits (Over 300 ms):** Show the dots after the delay, to avoid a flash.

### Replace Them With the Result

Keep the text length stable so the line does not reflow. If loading fails, show an error message in place of the dots.

**Do:** Replace the dots with the value when loading finishes.

```tsx
/**
 * Do example for "Replace Them With the Result" on the LoadingDots page.
 * Replace the dots with the value when loading finishes.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return <div {...styles.text()}>Network fee: $0.01</div>
}

namespace styles {
  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
}
```

**Don't:** Leave the dots beside the value after it arrives.

```tsx
/**
 * Don't example for "Replace Them With the Result" on the LoadingDots page.
 * Don't leave the dots beside the value after it arrives.
 * @module
 */
import { LoadingDots, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.text()}>
      Network fee: $0.01 <LoadingDots aria-label="Estimating network fee" size="small" />
    </div>
  )
}

namespace styles {
  export const text = style({ color: 'content.secondary', typography: 'body.b2' })
}
```

### Size Them to the Text

* **Small (small):** Dense text, such as table cells.
* **Medium (medium):** The default, beside body text.
* **Large (large):** Beside larger values or headings.

## Accessibility

LoadingDots renders a polite live region named "Loading". The dots carry no text.

### Semantics

* **Root (status):** Announced politely as "Loading" by default, after current speech.
* **Custom Name (aria-label):** Replaces the default "Loading" name with a more specific one.
* **Reduced Motion (reduce):** If the reader prefers reduced motion, the dots hold still at reduced opacity.

### Your Responsibilities

* **Say What Is Loading (aria-label):** Name it, such as "Estimating network fee", when "Loading" is too vague.
* **Keep Visible Text:** The dots are not focusable, and the accessible name is not visible. Keep text beside them.
* **Show One per Region:** Many status regions at once, such as one per table row, repeat the announcement.
* **Announce the Outcome (SC 4.1.3):** Announce the result or error in a live region when loading finishes.

## Related

[Spinner](/docs/components/spinner)

Use for a busy region or control.

[Skeleton](/docs/components/skeleton)

Use for content with a known shape.

[Button](/docs/components/button)

Use for an action's loading state.

[Loading](/docs/patterns/loading)

Covers choosing a loading indicator.
