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 avatarlet 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.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add avataruse 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
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
| Prop | Type | Default | Description |
|---|---|---|---|
avatarrequired | AvatarModel | — | Model. |
AvatarGroup
| Prop | Type | Default | Description |
|---|---|---|---|
avatarsrequired | Vec<AvatarModel> | — | Avatars. |
max | usize | 4 | Shown before the `+N` tile (4). |
total | Option<usize> | Default::default() | Total when the list is a page of a bigger set. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| — | 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.snapwhen it appears or changes. - Group members joining or leaving slide the stack instead of jumping; the
+Ncount rolls.
Timing
| Transition | Duration | Easing | Reduced motion |
|---|---|---|---|
| Picture fade-in | 180 ms + blur 4 → 0 | ease.out | 80 ms fade, no blur |
| Agent wave | 1200 ms loop | sine | still (full opacity) |
| Orbit ring | 1200 ms / turn | linear | static arc |
| Dashed ring | 3000 ms / turn | linear | static dashes |
| Breathe ring | 2000 ms loop | sine | steady ring |
| Done flash | 600 ms once | ease.out | none |
| Progress ring | 362 ms (spring.follow) | spring | jumps |
| Presence pop | 214 ms (spring.snap) | spring | none |
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,AvatarGroupfromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
AvatarElinoxyn_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.