# Thinking Orbs

> Animated thinking orbs for AI agent UIs: an open-source React component library (plus plain JS) with a state for each thing an agent does, like thinking, searching and compacting. No dependencies, built to read at 20px.

Website: https://thinkingorbs.com

## Installation

Install the package:

```bash
npm i @yogesharc/thinking-orbs
# or: pnpm add @yogesharc/thinking-orbs, yarn add @yogesharc/thinking-orbs, bun add @yogesharc/thinking-orbs
```

Or copy the React source into the project with shadcn, to own and edit it. It lands in `components/`, so import from `@/components/orb`:

```bash
npx shadcn@latest add https://thinkingorbs.com/r/orb.json
```

The React orb needs nothing but React; the plain JS one needs nothing at all.

## Usage

### React

```tsx
import { Orb } from "@yogesharc/thinking-orbs";

export function Thinking() {
  return (
    <span className="flex items-center gap-2 text-sm">
      <Orb state="reasoning" />
      Thinking
    </span>
  );
}
```

### Without React

```js
import { mountOrb } from "@yogesharc/thinking-orbs/vanilla";

// Draws into any <svg> on the page, in its CSS color.
const orb = mountOrb(document.querySelector("svg"), { state: "reasoning", label: "Thinking" });

orb.pause(); // hold it on its frame
orb.play(); // carry on
orb.destroy(); // remove it
```

## Props

All optional. `paused` and `className` are React only; `mountOrb` returns `pause()` and `play()` instead, and takes its color from the svg's CSS `color`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `OrbState` | `"base"` | What the agent is doing. |
| `variant` | `OrbVariant` | `"default"` | Which look of that state. |
| `size` | `number` | `20` | Width and height in px. |
| `speed` | `number` | `1` | Speed multiplier. |
| `shape` | `OrbShape` | — | Another form, from @yogesharc/thinking-orbs/shapes. |
| `render` | `OrbRender` | — | Another way to draw it, from @yogesharc/thinking-orbs/renders. |
| `density` | `number` | `1` | Dot count multiplier. |
| `dotSize` | `number` | `1` | Dot size multiplier. |
| `tilt` | `number` | `20` | Viewing angle from above, in degrees. |
| `paused` | `boolean` | `false` | Freezes the animation. |
| `label` | `string` | — | Name for screen readers. |
| `className` | `string` | — | Tint it with text-* classes. |

The orb draws in the text color (`currentColor`). With reduced motion it holds still.

## Shapes and renders

The orb is a sphere of dots. Other shapes and ways of drawing it are opt-in modules, so only what you import lands in the bundle. With shadcn, add them as `https://thinkingorbs.com/r/orb-shapes.json` and `https://thinkingorbs.com/r/orb-renders.json`.

```tsx
import { Orb } from "@yogesharc/thinking-orbs";
import { cube } from "@yogesharc/thinking-orbs/shapes";
import { halftone } from "@yogesharc/thinking-orbs/renders";

<Orb state="working" shape={cube} render={halftone} />
```

- `@yogesharc/thinking-orbs/shapes`: `cube`, `octahedron`, `tetrahedron`, `torus`.
- `@yogesharc/thinking-orbs/renders`: `dashes`, `squares`, `crosses`, `mesh`, `halftone`, `lines`, `verticalLines`.

Not every state suits every shape or render. A custom shape is an `OrbShape`, `{ points(count, look) }` returning [x, y, z] points inside the unit sphere; a custom render is an `OrbRender`, whose `mount` makes SVG elements and returns `dot(i, x, y, r, a, dx, dy)`. Define either outside the component.

## States

- `working`: Busy, running a tool.
  - `default`: A ring of light runs down it.
  - `gyro`: Wobbles like a spinning top.
- `reasoning`: Thinking.
  - `default`: One spark wanders over it.
  - `twins`: Two sparks wander at once.
- `searching`: Searching the web or files.
  - `default`: A lens hops between spots.
  - `lighthouse`: A beam sweeps round, like a lighthouse.
- `background`: Background tasks running, like a dev server.
  - `default`: Fewer, bigger dots.
  - `spiral`: The dots wound into spiral arms.
- `retrying`: Retrying after an error.
  - `default`: Spins, then winds back.
  - `surge`: Each turn launches fast and eases out.
- `compacting`: Compacting the context window.
  - `default`: Packs tight, then springs back past loose.
  - `squeeze`: Packs while wringing the top against the bottom.
  - `fuse`: Packs along a burning fuse line, with no bounce.
- `waiting`: Waiting for a usage limit to reset.
  - `default`: A comet spirals round it.
- `base`: Idle, or anything without its own state.
  - `default`: A plain spin.

## About

- Built by Yogesh: https://yogesharc.com
- X: https://x.com/yogesharc
- Sponsor: https://www.patreon.com/c/yogesharc
- GitHub: https://github.com/yogesharc/thinking-orbs
- License: MIT