Before you start
Purpose
AI products often still show a plain spinner or the word "Loading..." while the AI works in the background. Thinking Orbs replaces that with an animation matched to the actual task: searching, writing, connecting, or solving. This procedure installs the library and wires it into the spots where users currently wait on a blank spinner.
Who this is for
Developers and non-technical founders adding polish to an AI assistant, chatbot, dashboard, or tool built on React or Next.js.
Tools needed
- A React or Next.js project
- Node.js and npm
- The
thinking-orbspackage (open source) - Optional: an AI coding tool, if you are not writing the code yourself
Install the library
Thinking Orbs is an open source animation library. Install it directly into your project.
npm install thinking-orbs
Note
This procedure assumes a React or Next.js project. If your stack is different, check the repository for compatibility before continuing.
Pick the state that matches your AI's task
Thinking Orbs ships nine animation states. Match each one to a real moment in your product.
| State | Use it when |
|---|---|
| Working | The AI is generally processing something |
| Searching | The AI is looking for information |
| Solving | The AI is analysing or figuring something out |
| Listening | You have a voice assistant or audio input |
| Connecting | The AI is connecting to another tool or service |
| Weaving | The AI is bringing several pieces of information together |
| Composing | The AI is writing or generating a response |
| Breathing | A subtle idle or waiting state |
| Shaping | Something is being created or formed |
Note
You do not need all nine states. Pick only the ones your product actually uses.
Add your first orb
Import the component and render it wherever your interface currently shows a loading state.
import { ThinkingOrb } from 'thinking-orbs';
<ThinkingOrb state="searching" size={64} />
- To switch the animation, replace "searching" with any other state name: working, solving, listening, connecting, weaving, composing, breathing, or shaping.
Choose the right size for the placement
Thinking Orbs ships two sizes. Match the size to where the orb appears, rather than resizing one version with CSS.
| Size | Best for |
|---|---|
| 64px | AI assistants, chat interfaces, loading screens, agent activity, large status areas |
| 20px | Buttons, status messages, inline loading, small AI indicators |
Tip
The 20px version is built for tiny spaces. Use it instead of shrinking the 64px orb yourself.
Let an AI coding tool do the implementation
If you are not writing the code yourself, hand the setup to an AI coding tool.
- Open your project in your preferred AI coding tool.
- Paste the prompt below.
- Review the plan it gives you before it changes any files.
I want to add the Thinking Orbs library to this project.
Library:
https://github.com/Jakubantalik/thinking-orbs
Please:
1. Install thinking-orbs.
2. Check my existing design before changing anything.
3. Find places where the user currently waits for AI, loading, searching, writing or processing.
4. Add the most appropriate Thinking Orb state to those moments.
5. Use the 64px version for large AI states and the 20px version for inline states.
6. Match the orb to my existing light/dark theme.
7. Do not redesign the rest of the interface.
8. Keep the implementation simple and reusable.
9. Show me which orb state you used in each place and why.
Before making changes, briefly explain where you plan to use the animations.
Replace generic loading labels with a matching orb
Swap the label as well as the animation. The text should say what the AI is doing, not just that it is doing something.
| Old label | New label |
|---|---|
| "Loading..." | Searching orb, "Searching your documents" |
| "Generating..." | Composing orb, "Writing your response" |
| "Processing..." | Solving orb, "Analysing your data" |
Match the animation to what the AI is actually doing, instead of showing one generic spinner everywhere.
FAQs
Do I need to understand how the animations were built?
No. The library renders the animation. You only choose a state and a size.
Do I need to use all nine states?
No. Pick only the states that match what your product actually does.
Can the orb match my light or dark theme?
Yes. If an AI coding tool is doing the implementation, include theme matching in the setup prompt (see Step 5).
Where do I find the library if I need to check compatibility or updates?
The official project is open source on GitHub. See the link in Step 1.
Troubleshooting
Orb does not render
Confirm the import path matches how your package manager installed thinking-orbs, and that the component sits inside a client-rendered part of the app if you are on Next.js.
Orb clashes with your theme colors
Pass your theme's tokens into the component during setup rather than leaving the library defaults on a customised interface.
Orb is the wrong size in a button or status line
Use the size={20} prop directly. Do not scale size={64} down with CSS.
AI coding tool changes more than the loading states
Re-run the prompt and repeat the instruction not to redesign the rest of the interface.
Want more systems like this one?
The AI Challenge walks founders through building and shipping AI-powered workflows step by step.
See the AI Challenge →Version history
| Version | Date | Change |
|---|---|---|
| v1.0 | September 26, 2026 | Initial procedure created |