Avatar — HeroGPUI

Usage

Fallback text uses 14px text with 20px lines, or 16px text with 24px lines for large avatars.

Live example

Rust

1use herogpui::prelude::Avatar;
2
3Avatar::new("avatar-avatar")
4    .name("Jane Doe")

Live HeroGPUI compiled to WebAssembly. Select any example without loading another WASM instance.

Anatomy

Rust types

Avatar

Avatar is assembled from these builders. The API reference lists each one.

Customization

Appearance builders and theme tokens Avatar uses.

Styling

Avatar styling
Style	Description
`flex + items_center + justify_center + size(px(40.)) + flex_shrink_0 + overflow_hidden + control_radius + colors.default.color`	40px square at the 24px radius on `bg-default` for every color; the color only recolours the initials.
`Size::Sm => px(32.) + soft_radius; Size::Md => px(40.); Size::Lg => px(48.) + control_radius`	32/40/48px boxes; `sm` rounds one step tighter (at 32px a 24px radius would be all but a circle) and `md` restates nothing.
`let font = if self.large { px(16.) } else { px(14.) }`	The large avatar steps fallback text from 14px/20px to 16px/24px.
`fallback size_full + items_center + justify_center + text_size(font) + line_height(leading) + FontWeight::MEDIUM + soft_foreground(colors.foreground)`	A separate full-size fallback container centers initials or custom children with 14px/20px medium text in the color's soft foreground.
`img(data).size_full().rounded(radius)`	Draws the loaded image as the root's child, applies the same radius so every renderer clips it to the Avatar boundary, and does not interpolate the swap.
`fb_role.soft_foreground(colors.foreground)`	The five color classes only recolour the fallback text; the fill stays `bg-default` in the base variant.
`AvatarVariant::Soft => (fb_role.soft(), soft_fg)`	The soft variant clears the base fill and the compound rules paint the per-role soft mix behind the same soft-foreground text.

API reference

Builders

Avatar builders
Builder	Type	Default	Description
`size(Size)`	`Size`	`Size::Md`	Avatar size: 32/40/48px edge, with `sm` rounding one step tighter and `lg` stepping the fallback text up to 16px.
`color(Color)`	`Color`	`Color::Default`	Fallback color theme. The base avatar fills `bg-default` for every color — the color recolours the initials via the soft-foreground token.
`variant(AvatarVariant)`	`AvatarVariant`	`AvatarVariant::Default`	Visual style variant. `soft` clears the base fill and paints `bg-{role}-soft` with the same soft foreground.
`src(ImageSource)`	`ImageSource`	—	Image source URL. A plain string or path loads through gpui's asset system (a parseable URI is fetched, anything else is an embedded resource); the gpui `ImageSource::Image` / `Render` / `Custom` variants are the explicit parts for images the app already holds or loads itself.
`on_load(handler)`	`handler`	—	Callback when the image loads successfully and replaces the fallback. Fires once per source, on the first observed success, outside the layout phase; there is no event payload to hand over.
`on_error(handler)`	`handler`	—	Callback when there's an error loading the image; the fallback initials replace the image on that same failure. Fires once per source; no event payload.
`delay_ms(u64)`	`u64`	—	Delay before showing the fallback, measured from mount so a slow load does not flash the initials behind it. A success inside the window renders before it elapses; a failure inside it waits for the same window rather than restarting it.
`fallback_color(Color)`	`Color`	—	Override color from parent. Its own documented prop, not an alias: it overrides the parent `color` for everything the fallback paints, while the parent color still governs the rest.

Parts

Avatar parts
Part	Description
`Avatar`	Root container on the `.avatar` BEM class: `relative flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-3xl bg-default`. The name initials come from the port's own `name` builder (has no `name` prop); the load progress and the `delayMs` window key on the image source.
`Avatar`	`absolute inset-0 aspect-square size-full` image with an opacity transition. Draws the loaded image directly inside the root (`img(data).size_full().rounded(radius)`), applying the root radius to keep the image inside the Avatar boundary, and does not animate the swap.
`Avatar`	`flex size-full items-center justify-center bg-default text-sm font-medium` fallback box. The separate fallback container centers initials or custom `fallback` children with 14px/20px medium text (16px/24px for large avatars), painted `text-{role}-soft-foreground`.