# TypingDots

> A typing indicator for chat and AI assistant replies: calm dots that hand over to the message when it arrives, as a Web Component or in React.

TypingDots, Dotquilt's typing indicator, show that a reply is on its way. A slow wave passes through the dots; when the message arrives, it takes their place.

## Usage

Use TypingDots as a region's placeholder, inside the same bubble your message will fill.

**React**

```tsx title="AssistantReply.tsx"
'use client';
import { LoadingRegion, TypingDots } from '@dotquilt/react';
import { useEffect, useState } from 'react';

async function fetchReply(
  question: string,
  signal: AbortSignal,
): Promise<string> {
  const response = await fetch('/api/assistant', {
    method: 'POST',
    body: JSON.stringify({ question }),
    signal,
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const { reply } = await response.json();
  return reply;
}

export function AssistantReply({ question }: { question: string }) {
  const [reply, setReply] = useState<string | null>(null);
  const [failed, setFailed] = useState(false);

  useEffect(() => {
    const request = new AbortController();
    setReply(null);
    setFailed(false);
    fetchReply(question, request.signal)
      .then(setReply)
      .catch(() => {
        if (!request.signal.aborted) setFailed(true);
      });
    return () => request.abort();
  }, [question]);

  return (
    <LoadingRegion
      aria-label="Assistant reply"
      state={reply === null && !failed ? 'pending' : 'ready'}
      cycle={question}
      timing={failed ? { duration: 0 } : undefined}
      placeholder={
        <div className="bubble">
          <TypingDots />
        </div>
      }
    >
      <div className="bubble">
        {failed ? "Sorry, I couldn't answer that. Try again." : reply}
      </div>
    </LoadingRegion>
  );
}

export function Chat() {
  return <AssistantReply question="When is the Globex invoice due?" />;
}
```

**Native**

```html title="index.html"
<dotquilt-region id="reply" state="pending" aria-label="Assistant reply">
  <div slot="placeholder" class="bubble">
    <dotquilt-typing-dots></dotquilt-typing-dots>
  </div>
  <div class="bubble" data-reply></div>
</dotquilt-region>
```
```ts title="reply.ts"
import { type LoadingRegion, registerLoadingRegion } from 'dotquilt/region';
import { registerTypingDots } from 'dotquilt/typing';

registerLoadingRegion();
registerTypingDots();

const region = document.getElementById('reply') as LoadingRegion | null;
const bubble = region?.querySelector<HTMLElement>('[data-reply]');

export async function ask(question: string): Promise<void> {
  if (!region || !bubble) return;
  region.update({ state: 'pending', cycle: question });
  try {
    const response = await fetch('/api/assistant', {
      method: 'POST',
      body: JSON.stringify({ question }),
    });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    const { reply }: { reply: string } = await response.json();
    if (region.cycle !== question) return;
    bubble.textContent = reply;
    region.update({ state: 'ready' });
  } catch {
    if (region.cycle !== question) return;
    bubble.textContent = "Sorry, I couldn't answer that. Try again.";
    region.update({ state: 'ready', timing: { duration: 0 } });
  }
}

void ask('When is the Globex invoice due?');
```

TypingDots are decorative: they have no state of their own. On their own, outside a region, they keep their wave for four seconds and then rest.

## Accessibility

- **The dots are decoration.** They are hidden from assistive technology, so screen readers don't read them.
- **Label the region,** for example `aria-label="Assistant reply"`, so people know what is on its way. While it is pending, the message inside is skipped.
- **Announce the reply in your own words** if people need to hear it arrive, for example with a `role="log"` or `role="status"` element for the conversation. See [What screen readers hear](/docs/guides/motion/#what-screen-readers-hear).

## Options

| Attribute | React | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `count` | `count` | number | `3` | How many dots, up to 8. |
| `mark` | `mark` | `dot` \| `square` \| `dash` | `dot` | The shape of each dot. |
| `speed` | `speed` | number | `1` | How fast the wave moves. |
| `motion` | `motion` | `system` \| `paused` | `system` | `system` follows the visitor's reduced-motion setting; `paused` stills the dots. |

The dots are 8 px, 6 px apart. Change them with `--dotquilt-dot-size` and `--dotquilt-dot-gap`.
