Agent Avatar
ProWho is speaking in a multi-agent chat: a tinted avatar with the agent's initials, its name and an optional role.
Playground
Installation
Agent Avatar comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
AgentAvatar,
AgentAvatarSize,
AgentAvatarStatus,
} from "@wunderui/react"Then use it:
import { AgentAvatar } from "@wunderui/react"
export function Speaker() {
return <AgentAvatar name="Planner" role="Breaks the task into steps" initials="PL" color="indigo" status="working" />
}Expected result: You should see a 28 px indigo circle with PL and a small pulsing indigo dot on its top right, and next to it Planner in medium weight with Breaks the task into steps in grey underneath.
When to use
Use Agent Avatar for
- Saying which agent wrote a message in a thread that has more than one
- The header of a run or a card that belongs to one agent: tint, name and role
- A roster of the agents of a run, with Agent Status next to each
Use something else for
- Avatar for a person, a single assistant, or any avatar that needs an image or a presence dot
- Agent Status for what an agent is doing right now, in words, with the step and the time
- Handoff Divider for the moment one agent passes the conversation to another
Colour
Give each agent its own tint and keep it for the whole conversation. Indigo is the default, and grey is the quiet one for a generic assistant.
Size
Small is 24 px, medium (default) 28 px and large 36 px. The name and role scale with the avatar: 12, 13 and 14 px. With a role the two lines are as tall as the avatar (12 + 12, 14 + 14 and 20 + 16 px).
Status
A small indicator sits on the top right corner: a hollow ring for idle, a pulsing indigo dot for working, a red dot for failed. The state is spoken after the name, and AgentStatus adds time or reason.
Content
The role line is optional. Name and role wrap inside the width you give them, even an id with no space to break at.
Newer props
showName={false} shows the avatar alone and keeps the name for screen readers. ring adds a ring in the page colour so overlapping avatars stay apart.
Avatar only, ringed in a stack
Behavior and motion
What the avatar does with its content, its size, assistive technology and motion.
- Content
- Name and role can be any content, initials are a string, and the colour is one of ten Avatar tints (indigo by default). Nothing is derived from the name.
- Size
- Three sizes: small (24 px circle, 12 px name, 11 px role), medium (28, 13, 12, the default) and large (36, 14, 12). For bigger or an image, use the Avatar itself.
- Wrapping
- Name and role wrap inside their column and break anywhere when a word has no space. The circle never shrinks, so put the avatar in a column of the width you want.
- Status
- The indicator is a signal, not a report: it does not say which step, how long or why. Add Agent Status next to the avatar for that, so the state is a word and an icon too.
- Assistive technology
- A screen reader reads initials, name, the state if set, then the role. Tint and dot are not announced, so keep the name in the message text and announce status changes in a status line.
- Keyboard
- Not interactive and not in the tab order. Wrap it in your own link or button when a click should open the agent.
- Motion
- Only the working indicator moves: it pulses in opacity in an endless loop.
- Reduced motion
- With reduced motion on, the working dot stands still as solid indigo. The state is still spoken after the name.
Anatomy
The figure marks an avatar with a role, so without a role there is no number 5. The status indicator has no number because it shows only with a status.
- 1data-slot="agent-avatar"
An inline row that takes the width of its content, or of the column you put it in. It is a plain span: no role, no tab stop, no live region.
- 2
The library Avatar in 24, 28 (default) or 36 px: a circle in a mode-aware tint with matching letters. It never shows an image and has no border.
- 3
Two letters in the circle, 12 px medium. You pass them in; they are not derived from the name.
- Optional
With a status: an 8 px dot on the top right corner. Idle is a hollow ring, working a pulsing indigo dot, failed a red dot; screen readers hear the state after the name.
- 4
The name in medium weight, 12 to 14 px by size. It wraps and breaks anywhere without spaces, so a long id cannot push the row wider.
- 5Optional
The role in smaller secondary text under the name. Without a role the line is gone and the name sits centred beside the circle.
Best practices
- Do
Give each agent its own colour and keep it for the whole conversation. Name and role say the same in words, so the tint is never the only signal.
- Do
Add a short role such as Reviewer or Checks the result, so people know what the agent is responsible for. Drop it in a long thread where roles are known.
- Do
Pass the two-letter initials yourself. The avatar shows them as given and does not derive them from the name.
- Do
Use the status for a quick signal of who is busy, and add Agent Status when people need the step, the time or the reason. A dot alone says little.
- Don’t
Don't reuse a tint for two agents in one conversation. Name and role always render, but people scan the tint first.
- Don’t
Don't build a person's message header from it. It stands for an agent; use an Avatar with a name for a person so the two are easy to tell apart.
- Do
Announce a status change in a status line near the thread. The indicator and spoken state update, but a screen reader does not announce the change.
- Don’t
Don't use failed for an agent that merely returned nothing, and don't leave working on after the run ended. The dot is only as true as the state you pass.
API reference
AgentAvatar is a plain component, so the table lists every prop. It does not pass other props to the DOM.
An inline row that takes the width of its content, or of the column you put it in. It is a plain span: no role, no tab stop, no live region.
| Prop | Type | Default | Description |
|---|---|---|---|
| name required | ReactNode | — | The agent's name, in medium weight next to the circle. A node, so it can be styled. Required. |
| initials required | string | — | The letters inside the circle, as given. Two letters fit; the string is not shortened or derived from . Required. |
| role | ReactNode | — | What the agent is responsible for, in 12 px secondary text under the name. A node. Leave it out to draw the name alone. |
| color | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "indigo" | The tint of the circle: (default), , , , , , , , or . |
| size | "lg" | "sm" | "md" | "md" | (24 px), (28 px, default) or (36 px). The name and the role scale with it. |
| status | "idle" | "failed" | "working" | — | , or : the indicator on the top right of the circle. The state is also spoken after the name. Omit it for no indicator. |
| className | string | — | Extra classes for the row, for example in a column or a to set the width the text wraps at. |
| ring | boolean | false | A 2 px ring in the page colour, so avatars that overlap in a stack stay apart. |
| showName | boolean | true | shows the avatar alone. The name and role stay in the page for screen readers. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("agent-avatar")The full library index for assistants is at /llms.txt.