Thinking Orbs is a React component library of animated orbs that act as status indicators for AI agents. Each orb shows what an agent is currently doing — thinking, reasoning, searching, compacting, retrying, waiting, working, or handling background tasks — so that an AI interface can communicate activity instead of falling back on a generic spinner. It is built for developers and designers who are building AI-powered products in React and want polished, consistent indicators for every agent state, with attention paid to the detail of each state and variant. The library is free and open source. AI interfaces have outgrown simple loading states. When an agent is running, the user is waiting on work that has nuance: the model may be thinking through a problem, reasoning step by step, searching for information, retrying a failed request, compacting, or quietly continuing a background task. A single spinner or a static "Loading…" label collapses all of that nuance into one uninformative signal, and users are left guessing whether anything is happening at all. Thinking Orbs exists to give AI products a shared visual vocabulary for those moments. Rather than shipping one generic animation, the library treats each agent activity as its own state with its own look, and it is released free and open source so any React project can adopt it without licensing friction. The library centres on a set of orb states that map to common agent activities. The available states shown in the playground include Working, Reasoning, Searching, Background Tasks, Retrying, Compacting, Waiting, and Base. The state prop defaults to "base", so an orb rendered with no configuration at all still produces a valid, animated indicator. The remaining states are selected by name — for example — which means a developer can bind the orb directly to whatever status their agent or backend already reports, without inventing a new status model just for the UI. Because every state animates rather than sitting still, a running agent always looks alive on screen. Several states ship with a named variant that changes how that state looks. The playground lists Searching · Lighthouse, Working · Gyro, Reasoning · Twins, Background Tasks · Spiral, Compacting · Squeeze, Compacting · Fuse, and Retrying · Surge alongside their corresponding states. The variant prop defaults to "default", so variants are entirely opt-in: a team can start with the default look of a state and switch to a named variant later if it fits the product better, or use different variants of the same state in different parts of an interface. This keeps the concept count low while giving the same underlying state a different visual treatment depending on context. The Orb component is configured through props, and every prop is optional. state sets what the agent is doing and defaults to "base"; variant selects which look of that state and defaults to "default"; size sets width and height in pixels and defaults to 20; and speed is a speed multiplier that defaults to 1. For finer control over the animation, density is a dot count multiplier (default 1) and dotSize is a dot size multiplier (default 1), while tilt sets the viewing angle from above in degrees and defaults to 20. paused freezes the animation when set to true. label provides a name for screen readers, and className lets you tint the orb with text-* classes so it can inherit colour from a design system. Together these props mean the same component can be sized, slowed down, recoloured, paused, or made accessible to fit a wide range of interfaces. Beyond states and variants, the orb can be drawn in different ways. The core package ships one shape and one render, and other shapes and ways of drawing it are opt-in — as the site puts it, only what you import lands in your bundle. Shapes such as cube are imported from @yogesharc/thinking-orbs/shapes and renders such as halftone from @yogesharc/thinking-orbs/renders, then passed to the component, for example . This keeps the default bundle small while still allowing teams that want a distinct visual treatment to get one. The playground is where all of these combinations can be tried out. Installation is deliberately lightweight. The package can be installed from npm with npm, pnpm, yarn, or bun — npm i @yogesharc/thinking-orbs — or the React component can be copied into a project with shadcn. Dependency-wise, the site states plainly that the React orb needs nothing but React, and the plain JS one needs nothing at all, so there is no runtime baggage to audit. Usage is a single import and a single element: import { Orb } from "@yogesharc/thinking-orbs" and render the orb beside a text label, typically inside a flex row with the label styled with a text-sm class. The orb is drawn from a field of dots — the density and dotSize props scale how many dots are drawn and how large they are — and tilt controls the viewing angle from above, which gives the indicator its sense of depth. Speed scales the animation, and paused stops it dead when, for example, generation should halt. Because the component is small, prop-driven and dependency-free, wiring it into an existing AI interface is mostly a matter of mapping an agent status string to a state name and dropping the orb next to the label. The benefits follow from that: users get a clear, consistent signal about what an agent is doing; the interface no longer looks frozen during long operations; and the states give a product a way of naming activities such as compaction or retrying that would otherwise be invisible. Typical uses are exactly the moments where an AI product would otherwise show a spinner: an assistant reasoning before it answers, an agent searching, a system compacting or retrying work, or background tasks continuing while the user moves on. Designers and front-end engineers building AI chat, agent dashboards, or copilots in React are the natural audience, particularly teams that care about how each individual state looks. The playground on the site lets anyone preview every state, variant, shape and render before committing to one, and the project is supported through sponsorship on Patreon. In short, Thinking Orbs gives React AI interfaces a set of well-crafted, animated status indicators instead of a generic spinner. It covers thinking, reasoning, searching, compacting, retrying, waiting, working and background tasks; it offers multiple variants for states that need them; it is configurable through props for state, variant, size, speed, density, dot size, tilt and pausing; it supports opt-in shapes and renders that stay out of the bundle until imported; and it installs from npm, or can be copied in with shadcn, with no dependencies beyond React. Free and open source, it is a small component that makes the waiting moments in an AI product legible.

Thinking Orbs

Key Features

Use Cases

Who is this for?

Comments