Avatar

A black-bordered avatar frame with a role-keyed background, managed image, and placeholder.

Anatomy#

import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from "raft-ui";

<Avatar size="md" type="human">
  <AvatarImage src="/avatar.png" alt="" />
  <AvatarFallback />
  <AvatarBadge />
</Avatar>

Source AvatarSlot parsed pixel:*, uploaded human avatars, and Gravatar inside the component. Current Avatar keeps that app-domain resolution outside: callers pass a resolved image to AvatarImage, or leave AvatarFallback visible for placeholders and load failures.

Agent pixel

Agent image

Human image

Human placeholder

Badge#

The default dot and custom indicator both auto-scale with the avatar's size. Pass render={<Status />} when the indicator needsStatus variants or pulse — Status only owns its color and behavior.

Group#

Sizes#

xlprofile/detail · 64px

lglarge identity · 48px

mdpanel header · 36px

smlist rows · 32px

xscompact rows · 20px

2xsnav / DM rows · 18px

3xsinline preview · 14px

API#WIP

Avatar#

Prop	Type	Default	Description
`size`	"xl" \| "lg" \| "md" \| "sm" \| "xs" \| "2xs" \| "3xs"	—	Fixes the frame size and border width (xl 64px down to 3xs 14px).
`type`	"agent" \| "human"	—	Role-keyed bg: agent → cyan, human → lavender (+ text-black for the placeholder).
`children`	ReactNode	—	Composed parts: AvatarImage, AvatarFallback, AvatarBadge. Defaults to a placeholder AvatarFallback when empty.
`...props`	Base UI Avatar.Root.Props	—	Native span attributes (className for positioning, etc.).

AvatarImage#

Prop	Type	Default	Description
`...props`	Base UI Avatar.Image.Props	—	Managed image part. Fills the frame and reveals fallback while loading or on error.

AvatarFallback#

Prop	Type	Default	Description
`...props`	Base UI Avatar.Fallback.Props	—	Fallback part. Defaults to the scaled User icon when no children are passed.

AvatarBadge#

Prop	Type	Default	Description
`render`	useRender render prop	—	Optional element override. Default is the solid dot; pass render={<Status … />} for activity/presence chrome.
`...props`	useRender.ComponentProps<"span">	—	Corner shell on the avatar. The default dot and custom renders auto-scale from the parent size.

AvatarGroup#

Prop	Type	Default	Description
`...props`	ComponentProps<"div">	—	Overlapping avatar stack.

AvatarGroupCount#

Prop	Type	Default	Description
`...props`	ComponentProps<"span"> & { size: AvatarSize }	—	Trailing +N chip. Its size should match the sibling avatars.

Source differences#

Source AvatarSlot was a product-specific identity slot. Current Avatar is the reusable UI primitive: it keeps the frame, theme, image, fallback, badge, and group behavior, while app-domain lookup stays outside. Dropped exact sizes are handled by parent compositions, not by leaking every source callsite density into the public avatar API.

Area	Source	Current
API surface	AvatarSlot(context, type, agentAvatarUrl, humanAvatarUrl, gravatarHash, email)	Avatar(size, type) plus AvatarImage, AvatarFallback, AvatarBadge children
Identity lookup	AgentAvatar and GravatarAvatar are resolved inside AvatarSlot.	Callers resolve URLs; Avatar only owns image/fallback rendering state.
Size model	Ten callsite contexts, including 56px, 28px, 22px, and 18px one-offs.	Seven public sizes: xl, lg, md, sm, xs, 2xs, 3xs.
Inner sizing	Each context carries separate agent pixel, gravatar, and placeholder icon numbers.	Fallback, icon, badge, and border scale from the parent size.
Theme surface	Brutal square frame with role background and black border.	Theme-aware frame: brutal keeps square border; elegant uses the avatar family surface.
Extra parts	No badge or group primitive in AvatarSlot.	Badge and group are first-class composition parts.

Source context	Source frame	Source inner	Current size	Reason	Implementation
profile-tile	64px frame, 2px border	agent 60 / human 60 / icon 32	xl / 64px	This is a stable profile/detail scale, not a one-off layout adjustment.	Use <Avatar size="xl">; image/fallback fills the 64px frame.
account-tile	56px frame, 2px border	agent 52 / human 52 / icon 24	No exact public step	Only existed for account settings density, so keeping it would expose a layout-specific size as public API.	Use lg inside compact account rows or xl for profile emphasis; let the row/card own surrounding spacing.
mention-card	48px frame, 2px border	agent 44 / human 44 / icon 24	lg / 48px	Mention cards and identity popovers share this visual weight.	Use <Avatar size="lg"> inside hover-card or identity header compositions.
panel-header	36px frame, 2px border	agent 32 / human 32 / icon 18	md / 36px	Panel headers need a distinct step between list rows and mention cards.	Use <Avatar size="md"> in PanelHeader visual/icon slots.
surface-list	32px frame, 2px border	agent 28 / human 28 / icon 16	sm / 32px	This is the common list-row avatar size across source callsites.	Use <Avatar size="sm"> for list item leading media.
members-row	28px frame, 1px border	agent 26 / human 24 / icon 14	No exact public step	It was a narrow density correction for member rows and sits too close to both sm and xs.	Use sm when the row has normal text rhythm; use xs when the member avatar is secondary metadata.
creator-link	22px frame, 1px border	agent 20 / human 20 / icon 12	No exact public step	It belongs to inline link composition, not the avatar primitive scale.	Use xs and tune the link's gap/line-height in the parent composition instead of adding a 22px avatar size.
sidebar-list	18px frame, 1px border	agent 16 / human 16 / icon 10	2xs / 18px	Sidebar and DM rows need exact source density, so this stays a public compact step on the t-shirt scale.	Use <Avatar size="2xs"> inside SidebarItemIcon.
compact-list	20px frame, 1px border	agent 18 / human 18 / icon 12	xs / 20px	This is the reusable compact size for dense rows and metadata.	Use <Avatar size="xs"> for compact rows and dense metadata.
preview-mini	14px frame, 1px border	agent 14 / human 14 / icon 10	3xs / 14px	Inline previews need a true miniature avatar rather than shrinking xs ad hoc.	Use <Avatar size="3xs"> in quoted/preview chip compositions.