A tiny SVG orb that shows what your AI assistant is actually doing.
Thinking · working · waiting on you · done. Zero dependencies, 4 KB.

▶ Live demo · 中文文档

The hard part of AI UX isn't the loading — it's that every kind of waiting looks identical.

A spinner says "something is happening." An orb says which something — and when the model has stopped and is quietly waiting for your answer, it says that too. That last state is the one users miss most: the assistant asked a question, they walked away, and nothing on screen admits it's stuck.

• 🧠 Six states, each earned — idle thinking working asking done error. No decorative extras: every state maps to something your app actually knows.
• 👀 It looks at you — eyes track the cursor with 1.6px of travel. Small enough that nobody calls it an animation, big enough that everybody feels it.
• 🪶 4 KB, zero deps — plain SVG + vanilla JS. Works in React, Vue, Svelte, or a bare <script type="module">.
• 🎨 Themed with CSS variables — five lines to recolor. No build step, no config file.
• ♿ Accessible by default — every state carries an aria-label, and prefers-reduced-motion stops all animation while keeping the state readable.

npm i ai-orb

import { AgentOrb } from 'ai-orb'

const orb = new AgentOrb(document.querySelector('#orb'))

orb.state = 'thinking'   // model is composing
orb.state = 'working'    // long job running — the ring spins
orb.set('done', 3)       // finished, with an unread badge
orb.destroy()            // always clean up on unmount

Vue 3:

<script setup>
import { AgentOrb } from 'ai-orb/vue'
</script>

<template>
  <AgentOrb :state="state" :unseen="n" @click="openChat" />
</template>

That's the whole API.

Unknown values fall back to idle instead of throwing. State usually comes from a backend, and one typo shouldn't blank the page.

Everything is a CSS variable. Override them on the element (or any ancestor):

.agent-orb {
  --ao-size: 64px;
  --ao-hi:   #a5e9ff;   /* inner highlight  */
  --ao-mid:  #3aa8d8;   /* body             */
  --ao-lo:   #1c6a94;   /* outer edge       */
  --ao-glow: #3aa8d8;   /* halo             */
  --ao-ink:  #0d2733;   /* eyes             */
}

host is a mount point — the orb is appended to it, not swapped in. Throws if host is missing (silent failure gets misdiagnosed as a CSS problem).

Instance: orb.state, orb.unseen (both settable), orb.set(state, unseen?), orb.destroy(), orb.el (the button — use it to set CSS variables).

Also exported: STATES, DEFAULT_LABELS, css, injectStyle(doc?).

Styles auto-inject once per page. Import css instead if you manage styles yourself (SSR, strict CSP, or a custom theme pipeline).

Three deliberate limits — they're choices, not an unfinished roadmap:

1. Only six states. More states you can't tell apart at 56px is worse than fewer you can.
2. Only one thing spins. The ring is reserved for working, the longest wait. If everything moved, nothing would read as urgent.
3. No cartoon face. It has to sit in the corner of a serious product without becoming the loudest thing on screen.

Multiple orbs on one page share a single mousemove listener and one requestAnimationFrame loop; the last destroy() unbinds both. Gradient IDs are per-instance — with a shared ID, destroying the first orb turns every other one into an empty circle.

git clone https://github.com/webkubor/ai-orb
cd ai-orb
npm install
npm test

npx serve .   # then open http://localhost:3000/demo/

The demo imports the source directly — no build step. It must be served over HTTP: ES modules are blocked on file:// by CORS, which shows up as "the page loads but there are no orbs."

• MUSE AV — AI image studio. The orb is the collapsed state of its creation assistant, where image generation routinely takes 30–90 seconds.

Using it somewhere? Open a PR and add yourself.

MIT © webkubor