Skip to content
WunderUI

Agent Avatar

Pro

Who is speaking in a multi-agent chat: a tinted avatar with the agent's initials, its name and an optional role.

Playground

PLPlannerBreaks the task into steps

Installation

Agent Avatar comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  AgentAvatar,
  AgentAvatarSize,
  AgentAvatarStatus,
} from "@wunderui/react"

Then use it:

tsx
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.

PLPlannerBreaks the task into steps

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).

PLPlannerBreaks the task into steps

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.

WRWriterDrafts copy and docs

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.

PLPlannerBreaks the task into steps

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

NLNora, workingDODanielPRPriya, failed

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.

PLPlannerBreaks the task into steps
  • data-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.

  • 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.

  • 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.

  • 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.

  • Optional

    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.

PropTypeDefaultDescription
name requiredReactNode—The agent's name, in medium weight next to the circle. A node, so it can be styled. Required.
initials requiredstring—The letters inside the circle, as given. Two letters fit; the string is not shortened or derived from . Required.
roleReactNode—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.
classNamestring—Extra classes for the row, for example in a column or a to set the width the text wraps at.
ringbooleanfalseA 2 px ring in the page colour, so avatars that overlap in a stack stay apart.
showNamebooleantrue 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.

MCPget_component("agent-avatar")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.