Skip to content

Avatar

Initials on a colour of their own, a pixel mark for agents with a ring that follows the agent state, presence, a model badge, a progress ring and an overlapping group with +N.

oxyn add avatar
MCP
Dioxus
let mut av = AvatarModel::agent("Coder", &agent_state); // ring follows the state
av.size = 48.0;

rsx! {
    Avatar {
        avatar: av,
    }
}

// Overlapping group with a +N tile
rsx! { AvatarGroup { avatars: team, max: 4 } }

Rendered from Rust at build time · goes live when visible

When to use

  • Who is acting: a person, a workspace or an agent.
  • In agent apps several agents and people share a thread, so the avatar also has to say *what the agent is doing right now* without words: the ring around it follows AgentState.

When not to use

  • A dot and a label for any of the 13 agent states, as a pill, inline or a dot alone: use Status indicator instead.
  • A small status label that carries the colour: use Badge instead.
  • A launch countdown with digits that roll per unit, a compact one-line variant, hours absorbing days when days are hidden, and a live state with a pulsing dot at zero: use Countdown instead.

Installation

Avatar is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.

Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add avatar
Rust
use crate::oxyn::{Avatar, AvatarGroup, PRIMITIVES_CSS};

Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{Avatar, AvatarGroup, PRIMITIVES_CSS};

Usage

Dioxus · rust
let mut av = AvatarModel::agent("Coder", &agent_state); // ring follows the state
av.size = 48.0;

rsx! {
    Avatar {
        avatar: av,
    }
}

// Overlapping group with a +N tile
rsx! { AvatarGroup { avatars: team, max: 4 } }

Examples

Agent ring

Agent ring follows the state.

Code
let mut av = AvatarModel::agent("Coder", &agent_state); // ring follows the state
av.size = 48.0;

rsx! {
    Avatar {
        avatar: av,
    }
}

// Overlapping group with a +N tile
rsx! { AvatarGroup { avatars: team, max: 4 } }

Person

Initials and presence.

Code
let mut av = AvatarModel::person("Ada Lovelace");
av.size = 48.0;
av.status = Some(Presence::Online);

rsx! {
    Avatar {
        avatar: av,
    }
}

Progress

Progress ring and model badge.

Code
let mut av = AvatarModel::agent("Coder", &agent_state); // ring follows the state
av.size = 48.0;
av.ring = AgentRing::Progress(0.64);
av.model = Some("S".into());

rsx! {
    Avatar {
        avatar: av,
    }
}

Workspace

Rounded square for a workspace.

Code
let mut av = AvatarModel::person("Northwind Labs");
av.size = 48.0;
av.shape = AvatarShape::Square;

rsx! {
    Avatar {
        avatar: av,
    }
}

API reference

Avatar

PropTypeDefaultDescription
avatarrequiredAvatarModel—Model.

AvatarGroup

PropTypeDefaultDescription
avatarsrequiredVec<AvatarModel>—Avatars.
maxusize4Shown before the `+N` tile (4).
totalOption<usize>Default::default()Total when the list is a page of a bigger set.

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
—Not focusable on its own

Accessibility

  • role=img with a full name ("Coder, thinking", "Ada Lovelace, online").
  • The group is a role=group named by its members ("… and 2 more").
  • The ring and the twinkling mark stop under prefers-reduced-motion.
From the spec

role=img with a full name: "{name}, {presence}, {ring word}". Pictures have empty alt (the container is named). Groups are role=group named with the visible names and "and N more". Ring colours always come with the word, never colour alone.

Motion & interaction

  • Picture fades in once loaded, over the initials — never an empty circle while it loads; a cached picture shows at once (Arc).
  • Agent mark: cells fade down and back in a diagonal wave, 1.2 s, each cell offset by (row + col) × 150 ms.
  • Presence dot pops in on spring.snap when it appears or changes.
  • Group members joining or leaving slide the stack instead of jumping; the +N count rolls.
Timing
TransitionDurationEasingReduced motion
Picture fade-in180 ms + blur 4 → 0ease.out80 ms fade, no blur
Agent wave1200 ms loopsinestill (full opacity)
Orbit ring1200 ms / turnlinearstatic arc
Dashed ring3000 ms / turnlinearstatic dashes
Breathe ring2000 ms loopsinesteady ring
Done flash600 ms onceease.outnone
Progress ring362 ms (spring.follow)springjumps
Presence pop214 ms (spring.snap)springnone

Responsive behaviour

  • Seven sizes from 12 to 96 px; presence and the model badge scale with it.
  • In a group, overlapped initials stay centred in the part that is visible.
Edge cases (spec)

Tiny sizes (12–16 px): the presence dot is at least 6 px; the ring pad shrinks to 2 px; initials drop to one letter's width. Broken image URLs fall back to initials. Very long names only affect the accessible name. Groups with total larger than the list show the remainder in +N. In dense lists, the ring animations count against the shared motion clock (orbit at 60 Hz; the clock's unfocused / low-power caps apply).

Notes for AI

  • Import Avatar, AvatarGroup from oxyn_dioxus and include PRIMITIVES_CSS plus the token stylesheet once.
  • A GPUI version exists: AvatarEl in oxyn_gpui.
  • Props to set first: avatar, avatars.
  • Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI