AIPresence
StableA moving lime disc that shows whether the assistant is waiting, listening, thinking, speaking, or has hit a problem.
Also known as voice orb, ai avatar, assistant indicator, orb
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Switch between states
const [state, setState] = useState<AIPresenceState>("listening");
<AIPresence state={state} size="lg" />
{(["idle", "listening", "thinking", "speaking", "error"] as const).map((s) => (
<Button key={s} size="sm" onClick={() => setState(s)}>{s}</Button>
))}
<Button size="sm" variant="ghost" onClick={() => setState("idle")}>Stop</Button>The disc glides between states. The label and the hidden message for screen readers change only when the state does.
When to use it
A drawn disc that shows what a voice assistant is doing: waiting, listening, thinking, speaking or stuck. It glides between states instead of restarting, and the state is always given in words too.
Made of: Halo · Disc · AI mark · Thinking arc · Listening rings · State label · Hidden status message
Use it for
- A voice conversation, to show whether the assistant is listening or speaking.
- The pause while the assistant thinks between voice turns.
- Reacting to how loud the speaker is: pass level.
Not for
- Showing who wrote a message: use Avatar.
- A whole voice screen with its controls: use VoicePanel.
- The wait before a text reply: use TypingIndicator.
Do and avoid
Do
- Place a labelled Stop button beside the disc whenever the person can interrupt.
- Ask for microphone permission when the person presses a button, then start the disc.
- Keep the label showing unless the state is written out nearby.
- Pass the raw volume and let the disc smooth it.
Avoid
- Make the disc the only button or the only sign of what is happening.
- Change the state many times a second. Screen readers announce only real changes.
- Use amber for the problem state. Amber is only for when a person has to act.
- Add a glow outside the disc, or use rainbow or purple gradients.
On a phone
- The disc is a fixed size (32, 64 or 112px) and does not scale with the screen, so pick the size that fits a narrow screen.
- The disc and its label sit on one row, so a long label can squeeze a small screen. Keep the label short.
- It is not a control. Place a Stop button beside it, which has a 44px tap area on touch screens.
- Under reduced motion it draws a still frame instead of the animation.
Seen in products
- The 21st.dev article lists the states as idle, connecting, listening, thinking, speaking and error. It suggests one smooth animation that changes with the state.
- It suggests smoothing the microphone volume, because raw values jump around. It says simple drawings are cheap and enough for decoration or thinking.
- For people who turn off motion, it suggests a still picture with words and no reaction to volume.
- It suggests announcing the state to screen readers, never making the disc the only button, and asking for the microphone when a button is pressed.
- Shape of AI lists voice as one of four avatar styles. It suggests clear changes between listening, working and waiting.
- A search snippet says Siri in iOS 26 became a dark orb that pulses while listening and reacts to speech.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| state | "idle" | "listening" | "thinking" | "speaking" | "error" | "idle" | Current state. Each state is a row of animation targets. |
| size | "sm" | "md" | "lg" | "md" | 32, 64 or 112 pixels. |
| level | number | 0 | Audio amplitude from 0 to 1. Smoothed inside the component. Ignored under reduced motion. |
| showLabel | boolean | true | Show the state as visible text. The status region is present either way. |
| labels | Partial<Record<AIPresenceState, string>> | none | Replace the text for any state. |
| className | string | none | Extra classes for the wrapper. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one AIPresence switches all of this from its properties panel, across 30 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| Status | state | Idle, Listening, Thinking, Speaking, Error |
| Size | size | SM, MD, LG |
| Show label | showLabel | On or off |
Tokens
Change one of these and every part that uses it follows.
--code-bg--fg-subtle--lime--danger--fg-muted--danger-fg
Built in
- Screen readers hear the state in words, politely, each time it changes.
- The drawing is hidden from screen readers.
- For people who turn off motion, the disc stays still, ignores volume and changes state instantly.
- The problem state shows the words "Something went wrong", not only a red center.
What you need to do
- Put a labelled Stop button next to it whenever people can interrupt. The disc is not a button.
- Change state only when the assistant really changes what it is doing. Screen readers hear each change.
- Keep the visible label on, unless the state is written out nearby.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide