# Agent Thinking

> A small orb of ink dots with a status line beside it, for an agent that is idle, listening, thinking or speaking.

```tsx
'use client';

import { useState } from 'react';
import { AgentThinking, Button } from '@brand-studio/ui';

const states = [
  { state: 'idle', label: 'Ready when you are' },
  { state: 'listening', label: 'Listening' },
  { state: 'thinking', label: 'Comparing roast notes' },
  { state: 'speaking', label: 'Answering' },
] as const;

export default function AgentThinkingDemo() {
  const [current, setCurrent] = useState<(typeof states)[number]>(states[2]);
  return (
    <div style={{ display: 'grid', justifyItems: 'center', gap: 40 }}>
      <AgentThinking state={current.state} label={current.label} size={72} />
      <div style={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'center', gap: 8 }} role="group" aria-label="Agent state">
        {states.map((item) => (
          <Button key={item.state} tone={item === current ? 'primary' : 'secondary'} shape="pill" aria-pressed={item === current} onClick={() => setCurrent(item)}>
            {item.state}
          </Button>
        ))}
      </div>
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, AgentThinking } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { AgentThinking } from '@brand-studio/ui';
```

```tsx
<AgentThinking state="thinking" label="Comparing roast notes" />
```

## Examples

### Sizes

`size` sets the orb's width in pixels. Below 64 pixels it draws fewer dots so it stays crisp next to text.

```tsx
import { AgentThinking } from '@brand-studio/ui';

export default function AgentThinkingSizes() {
  return (
    <div style={{ display: 'grid', gap: 24, justifyItems: 'start' }}>
      <AgentThinking size={20} label="Searching 14 orders" />
      <AgentThinking size={48} state="listening" />
      <AgentThinking size={96} state="speaking" />
    </div>
  );
}
```

## Accessibility

- The component has `role="status"`. With `label` it shows and announces that text; without it, screen readers hear the state name.
- Each state has its own shape and motion, so it does not rely on colour alone. The orb pauses off screen. Under reduced motion the dots hold still and the label stays.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `state?` | `"idle" \| "listening" \| "speaking" \| "thinking"` | `'thinking'` |
| `size?` | `number` | `64` |
| `label?` | `string` | – |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/agent-thinking/
