# Thinking orbs
> Ten small animated dot orbs that say an assistant is busy, and how, with a gallery of them in pills and a playground.
Loading indicators for an AI interface, drawn in dots on a canvas: a lattice globe that tumbles while solving, a globe swept by a beam while searching, one that squashes to a voice while listening, a wired cloud while connecting, a hollowed shell under a moving waterline while composing, orbits while working, a ring of dashes that breathes, rings that weave, an outline that turns from triangle to square to circle, and a quiet ring for thinking. A change of state morphs: the dots glide to their new places. Below them, a playground tries every state with its size, speed, colour, dot count, dot size and a pull toward the cursor.
A React component by Bruno Delorence: https://brunodelorence.com/components/thinking-orbs. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: AI.
## Anatomy
1. **Stage**: A quiet cell the orb sits centred in: at least 586 px tall beside the controls, and 360 px once they wrap under it.
2. **Orb**: The `ThinkingOrb` box: it takes `size` in the layout, square, and holds the ink in its CSS colour.
3. **Canvas**: Half the size bigger than the box, a quarter on each side, so dots pulled toward the cursor are not cut off. It draws only while on screen.
4. **Play and pause**: Holds one still frame (the `paused` prop) or lets it run again; it reads Play while paused.
5. **State tabs**: The ten states as one radio group: arrows move and choose, and a screen reader hears the new state.
6. **Sliders**: Speed, dot count and dot size, each a filled pill with its name and value inside, over a real range input.
7. **Colour swatches**: Mono and four named inks, each with a light and a dark shade; the chosen one is ringed.
8. **Code**: The `ThinkingOrb` line for what is set, only the props that differ from their defaults, with a copy button.
## When to use
- An assistant that is busy for a few seconds and can say how: searching, writing, listening, connecting, solving.
- A status line in a chat, beside a few words: a 20 px orb in a pill reads at text size, a 56 px one heads a turn.
- Work whose kind changes while it runs: a change of `state` morphs the dots in 700 ms instead of swapping icons.
- A voice or agent surface that needs one quiet sign of life, in the page’s ink or a named one, in light or dark.
## When not to use
- Progress you can measure. Use a progress bar or a percentage, so people know how long is left.
- A wait on a button or a form field. Use the button’s own busy state, with a plain spinner at text size.
- Waits under half a second: the orb never settles and reads as a flicker. Show nothing, or the result.
- Many busy rows at once, in a table or a list: a column of moving globes competes for attention. Use a static status per row.
- Errors and stopped work: every state means busy. Say what failed, or that it stopped, in words.
## Installation
Install it with the shadcn CLI, into components/thinking-orbs of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/thinking-orbs.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { ThinkingOrb } from './thinking-orbs';
export function AssistantStatus({ busy }: { busy: 'searching' | 'composing' | null }) {
if (!busy) return null;
return (
{busy === 'searching' ? 'Searching the docs…' : 'Writing…'}
);
}
```
## States
- **Working**: Short trains of nodes run round thirteen tilted orbits, each traced in faint specks.
- **Searching**: A globe of latitude rings; a beam picks a new spot on its front every 0.72 s and lights the dots under it.
- **Solving**: The lattice tumbles a quarter turn every 1.2 s, its dots scattering a little mid-turn.
- **Listening**: The globe squashes and stretches to a voice level while a bright band runs up and down its rings.
- **Connecting**: About seventy nodes, each wired to its three nearest, turning about a tilted axis.
- **Composing**: A dense shell under a rippling waterline: lit above it, only the dim inside below, so it reads as a bowl.
- **Breathing**: A ring of 56 short dashes on a blob whose edge drifts in and out.
- **Weaving**: Three rings of dots turning against each other, each dot swinging across its neighbours.
- **Shaping**: 24 dots walk a triangle, a square and a circle, about a second each, morphing between them.
- **Thinking**: The default: a quiet ring of 20 dots on a drifting blob.
- **Paused**: `paused` holds one still frame. Under reduced motion every orb is drawn still like this.
- **Text size**: `size={20}`: globes thin to 60% of their rings so they stay legible, and sub-pixel dots draw as squares.
- **Named ink**: `color="sky"`: each named ink has a light and a dark shade, picked by the colour scheme.
- **Any CSS colour**: `color="#7c5cff"`, or `currentColor` to follow the text around it.
- **Denser, bigger dots**: `density={1.5}` and `dotSize={1.5}`: half as many dots again, half as big again.
- **Dark**: In a dark colour scheme mono turns near-white; the orb reads its colour every frame, so a theme switch shows at once.
## How it works
- Each state is a painter: a function of time that writes the frame’s dots (x, y, size, alpha, in units of the orb’s radius) into flat typed arrays reused every frame. Painters keep no state, so any moment can be drawn: a still frame under reduced motion, or the old state while it morphs into the new one.
- The globes are points on latitude rings, as many on a ring as its girth allows, turned by a yaw and a pitch with a light perspective; the far side fades or hides, and nearer dots draw bigger and brighter.
- Solving tumbles the lattice a quarter turn at a time, every 1.2 s with an ease in and out: twelve turns about x, y or z and then their undoing, so it comes back to where it began. Mid-turn the dots scatter a little and settle back on the lattice.
- Searching lights one patch at a time: a beam picks a new spot on the front every 0.72 s and rises and falls there, the dots under it growing and brightening. Listening squashes and stretches the globe with a voice level made of three sines, while a bright band runs up and down its rings.
- Composing is a dense shell of meridians stopped short of the poles. A waterline across the view, high in the middle and low at the sides, ripples with two sines: above it the near side is lit, below it only the inside of the far side shows, dim, so the shell reads as a bowl.
- Connecting wires each of about seventy nodes on a sphere to its three nearest, once, and turns the whole cloud about a tilted axis; lines and nodes fade with depth. Working runs short trains of nodes round thirteen tilted orbits, each orbit traced in faint specks.
- Breathing is a ring of 56 short dashes on a blob whose radius is three sines of the angle drifting in time; thinking is the same idea in 20 dots; weaving turns three rings of dots against each other, each dot swinging in and out across its neighbours; shaping walks 24 dots round a triangle, a square and a circle, 1.07 s each, and morphs between them in 0.36 s.
- A change of state runs both painters for 700 ms: dot i of the old one glides to dot i of the new one, size and alpha blending too, and dots without a partner fly from (or to) one while fading. Lines cross-fade.
- The canvas is half the orb’s size bigger than its box on each side, so dots pulled toward the cursor (gravity: within 2.5 sizes, by up to 0.3 of a size, eased in and out) are not cut off; the box still takes only `size` in the layout. It is sharp at up to twice the pixel ratio, and smaller orbs thin their globes out so they stay legible.
- The dots are drawn in the canvas’s CSS colour, read back each frame, so the colour prop, a theme or a scheme change shows at once, transition included. Each orb draws only while on screen.
- The pills’ words are dim, with a band of light that runs through them every 2 s: a copy of the text on top, clipped to a gradient four times its width that slides from right to left.
- While on screen and untouched, the playground walks through the states, 3.2 s on each; any press or key in it hands it to the reader for 8 s.
## API reference
- **state** (`'working' | 'searching' | 'solving' | 'listening' | 'connecting' | 'composing' | 'breathing' | 'weaving' | 'shaping' | 'thinking'`, default `'thinking'`): ThinkingOrb: what the orb shows. A change morphs from the old state to the new one in 700 ms.
- **size** (`number`, default `64`): ThinkingOrb: its width and height in px. Tuned at 64, 32 and 20; smaller orbs draw fewer dots on their globes.
- **color** (`'mono' | 'sky' | 'amber' | 'rose' | 'mint' | string`, default `'mono'`): ThinkingOrb: a named ink, each with a light and a dark shade, or any CSS colour. The showcase’s color prop sets it for every orb.
- **speed** (`number`, default `1`): ThinkingOrb: how fast it moves; 1 is the tuned pace.
- **dotSize** (`number`, default `1`): ThinkingOrb: how big its dots are; 1 is the tuned size.
- **density** (`number`, default `1`): ThinkingOrb: how many dots, as a share of the state’s own count.
- **gravity** (`boolean`, default `false`): ThinkingOrb: whether the dots lean toward a nearby cursor.
- **paused** (`boolean`, default `false`): ThinkingOrb: hold a still frame.
- **label** (`string`): ThinkingOrb: what screen readers hear (the state’s name by default); an empty string hides the orb from them, for when words next to it say the same.
- **defaultState** (`OrbState`, default `'listening'`): ThinkingOrbs (the showcase): the state the playground starts on.
- **gallery** (`boolean`, default `true`): ThinkingOrbs: whether to show the gallery of pills above the playground.
- **autoplay** (`boolean`, default `true`): ThinkingOrbs: whether the playground walks through the states on its own, while on screen and untouched.
- **colorScheme** (`'light' | 'dark' | 'system'`): ThinkingOrbs: the colour scheme; without it, the page’s.
- **className** (`string`): A class for the root, on either component.
## Accessibility
- An orb is an image named for its state (“Searching…”), or hidden from screen readers with label="" when the words beside it already say it; the canvas itself is always hidden.
- The playground’s choices are radio groups of buttons: Tab reaches the chosen one, the arrows (and Home, End) move and choose. Speed, dots amount and dot size are real range inputs with their values spoken; the colours are a radio group of named swatches.
- A state the reader picks is announced politely; the demo’s own changes are not, so it never chatters.
- Focus rings show for keyboard use. The play button says whether the orb is paused (aria-pressed).
- Under reduced motion the orbs hold a still frame, states change without a morph, the words’ light stops and the demo never plays.
## Source
### thinking-orbs/thinking-orbs.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
import { ThinkingOrb, type OrbColor } from './orb';
import { STATE_LABELS, STATES, type OrbState } from './states';
import { useAutoplay } from './use-autoplay';
import styles from './thinking-orbs.module.css';
export { ThinkingOrb, type OrbColor, type ThinkingOrbProps } from './orb';
export { STATES, type OrbState } from './states';
/*
* Thinking orbs: small animated dot drawings that say an assistant is busy, and how: working,
* searching, solving, listening, connecting, composing, breathing, weaving, shaping or thinking.
* Each is a canvas of dots (orb.tsx) that a painter (states.ts) lays out frame by frame: globes
* of latitude rings that turn, squash or tumble, a wired cloud, orbits, rings and outlines.
*
* - This file is the showcase: a gallery of orbs in pills, as they would sit in a chat, their
* words lit by a band of light that runs through them; and a playground, where the state, the
* size, the cursor's pull, the speed, the colour, the number and size of the dots can be tried,
* with the code to match.
* - A change of state morphs: the old dots glide to the new ones' places in 700 ms.
* - While on screen and untouched, the playground walks through the states, 3.2 s on each. Any
* press or key in it hands it to the reader.
* - Light or dark: every colour is a light-dark() token, so it follows the page's color-scheme, or
* the colorScheme prop. The orbs draw in their CSS colour, so they follow too.
*/
type Cell = { state: OrbState; words: string; size: 'big' | 'small' };
/** The gallery's two columns, as tall as each other. */
const COLUMNS: Array> = [
[
{ state: 'solving', words: 'Solving…', size: 'big' },
{ state: 'listening', words: 'Listening to you…', size: 'small' },
{ state: 'searching', words: 'Searching…', size: 'big' },
{ state: 'weaving', words: 'Drafting a plan…', size: 'small' },
{ state: 'thinking', words: 'Thinking it over…', size: 'small' },
],
[
{ state: 'composing', words: 'Writing…', size: 'big' },
{ state: 'working', words: 'Working…', size: 'big' },
{ state: 'connecting', words: 'Linking ideas…', size: 'big' },
{ state: 'shaping', words: 'Shaping the layout…', size: 'small' },
],
];
const SIZES = [64, 20, 32] as const;
const COLORS: Array<{ id: OrbColor; name: string }> = [
{ id: 'mono', name: 'Mono' },
{ id: 'sky', name: 'Sky' },
{ id: 'amber', name: 'Amber' },
{ id: 'rose', name: 'Rose' },
{ id: 'mint', name: 'Mint' },
];
const DEMO_STEP = 3200;
/** A row of tabs that acts as one radio group: arrows move and choose, Tab leaves. */
function Choice({
label,
options,
value,
onChange,
name,
part,
}: {
label: string;
options: readonly T[];
value: T;
onChange: (value: T) => void;
name: (value: T) => string;
part: string;
}) {
const buttons = useRef>([]);
const onKey = (event: ReactKeyboardEvent, index: number) => {
const step = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[event.key];
let next = step === undefined ? -1 : (index + step + options.length) % options.length;
if (event.key === 'Home') next = 0;
if (event.key === 'End') next = options.length - 1;
if (next < 0) return;
event.preventDefault();
onChange(options[next]);
buttons.current[next]?.focus();
};
return (
{label}
{options.map((option, index) => (
))}
);
}
/** A slider drawn as a filled pill, its name and value inside; a real range input does the work. */
function Slider({
label,
min,
max,
step,
value,
onChange,
format,
part,
}: {
label: string;
min: number;
max: number;
step: number;
value: number;
onChange: (value: number) => void;
format: (value: number) => string;
part: string;
}) {
const share = ((value - min) / (max - min)) * 100;
return (