thinking-orbs

Thinking Orbs

Core Contract

1. Use thinking-orbs in React 18+ interfaces that need indeterminate AI activity feedback.
2. Map the real product lifecycle to one of the six shipped states.
3. Use only the tuned 20 or 64 pixel size. Do not stretch one preset into another.
4. Keep theme="auto" unless the surrounding surface has a known fixed theme.
5. Pair the orb with concise visible status text when the activity matters to the user.
6. Override aria-label with a task-specific label, or hide the orb from assistive technology when adjacent live text already announces the same state.
7. Use paused to freeze the current frame. Do not simulate pause with speed={0}.
8. Treat the orb as indeterminate feedback, never as a progress percentage or completion signal.

The package renders monochrome dots on a transparent 2D canvas. It does not expose custom colors, arbitrary sizes, or determinate progress.

Install

Inspect the project package manager, then install:

npm install thinking-orbs

The package declares react and react-dom version 18 or newer as peer dependencies. Import the component and exported types from the package root:

import {
  ThinkingOrb,
  type OrbSize,
  type OrbState,
  type OrbTheme,
  type ThinkingOrbProps,
} from "thinking-orbs";

Choose the State

• working — generic tool execution, multi-step work, or an activity without a more precise state.
• searching — retrieval, web search, file search, or knowledge lookup.
• solving — reasoning, analysis, calculation, or planning.
• listening — microphone input, speech capture, or waiting for a spoken turn.
• composing — writing, summarizing, drafting, or generating a text response.
• shaping — creating or refining an image, layout, structured artifact, or other formed output.

Prefer a truthful generic working state over a visually interesting but inaccurate state. Change the state only when the underlying activity changes.

Choose the Size