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

• Use size={20} inline with text, inside buttons, or in compact status rows.
• Use size={64} at chat-avatar scale, in an empty state, or as the main visual status.

The presets have different dot counts, dot sizes, and speed tuning. They are separate designs rather than a scale factor. If the layout needs more surrounding space, size the wrapper instead of applying CSS transforms to the canvas.

Basic Usage

import { ThinkingOrb } from "thinking-orbs";

export function AgentStatus() {
  return (
    <ThinkingOrb
      state="searching"
      size={20}
      theme="auto"
      aria-label="Searching project files…"
    />
  );
}

All other canvas props pass through, including className, style, data-*, event handlers, and ARIA attributes.

Model the Product Lifecycle

Keep product phases separate from visual states so the mapping stays explicit:

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

type AgentPhase =
  | "idle"
  | "retrieving"
  | "reasoning"
  | "writing"
  | "creating"
  | "done"
  | "error";

const ORB_BY_PHASE: Partial<Record<AgentPhase, OrbState>> = {
  retrieving: "searching",
  reasoning: "solving",
  writing: "composing",
  creating: "shaping",
};

export function AgentActivity({ phase }: { phase: AgentPhase }) {
  const state = ORB_BY_PHASE[phase];
  if (!state) return null;

  return <ThinkingOrb state={state} size={20} />;
}

Remove the orb on done, error, cancellation, or idle. Show the appropriate result, retry, or error UI instead of leaving the last activity animation running.

Announce Status Once

The component defaults to role="img" with a per-state label such as “Searching…”. When visible text describes the same state, make the text the single announcement source:

export function LiveAgentStatus() {
  return (
    <div role="status" aria-live="polite" className="agent-status">
      <ThinkingOrb state="solving" size={20} aria-hidden="true" />
      <span>Reviewing the repository…</span>
    </div>
  );
}

Use aria-live="polite" for ordinary phase changes. Avoid rapid label churn. Do not add another hidden live region when role="status" already owns the announcement.

Theme

Use one of:

<ThinkingOrb theme="auto" />
<ThinkingOrb theme="dark" />
<ThinkingOrb theme="light" />

• auto first checks an ancestor data-theme="dark|light" attribute or dark / light class.
• If no ancestor theme exists, auto follows prefers-color-scheme.
• Theme changes update live.
• dark means light dots intended for a dark background.
• light means dark dots intended for a light background.

The canvas is transparent. Verify contrast against the actual surface rather than the page root alone.

Speed and Pause

<ThinkingOrb state="working" speed={0.85} />
<ThinkingOrb state="composing" paused={isWaitingForApproval} />

speed multiplies the baked speed of the selected state and size. Start at 1; use roughly 0.75–1.25 for subtle product tuning. Extreme values can make the hand-tuned motion feel frantic or stalled.

paused freezes the current frame while retaining the visual status. Remove the component when the activity has actually ended.

Next.js and Client Rendering

The component uses React effects, canvas, requestAnimationFrame, media queries, and observers. Keep the package import behind a client boundary in the Next.js App Router:

"use client";

import { ThinkingOrb } from "thinking-orbs";

export function ThinkingStatus() {
  return <ThinkingOrb state="working" size={20} />;
}

The library is SSR-safe because it paints only on the client after resolving the theme. A client boundary is still required where the framework enforces server and client component separation.