Avatar
A square sticker frame with an ink edge, a role-keyed background, managed image, and placeholder.
Controls
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
The default dot and custom indicator both auto-scale with the avatar's size. Pass render={<Status />} when the indicator needs Status variants — Status only owns its color.
presence sets the default dot's status light: online (the default), busy for an agent at work, error, offline, or external. The light never animates; label it when no word sits beside it.
WBMMCR
offset places the badge anywhere on the avatar. It is the position of the badge's centre, measured from the avatar's top-left corner, as [x, y]. Numbers are px; strings are any CSS length, and percentages are of the avatar's size — so the four corners are [0, 0], ["100%", 0], [0, "100%"] and ["100%", "100%"] at every size. Without offset the badge keeps the default bottom-right spot; size and stacking stay owned by the avatar either way.
xlprofile/detail · 99px
lglarge identity · 51px
mdpanel header · 35px
smlist rows · 27px
xscompact rows · 19px
2xsnav / DM rows · 19px
3xsinline preview · 14px
size"xl" | "lg" | "md" | "sm" | "xs" | "2xs" | "3xs"
Fixes the frame size on the DS 8n + 3 steps: xl 99, lg 51, md 35, sm 27, xs and 2xs 19, 3xs 14px. The ink edge stays 1.5px at every size.
type"agent" | "human"
Role-keyed background: agent → stone until its sprite covers it, human → lavender.
childrenReactNode
Composed parts: AvatarImage, AvatarFallback, AvatarBadge. Defaults to a placeholder AvatarFallback when empty.
...propsBase UI Avatar.Root.Props
Native span attributes (className for positioning, etc.).
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xl" | "lg" | "md" | "sm" | "xs" | "2xs" | "3xs" | — | Fixes the frame size on the DS 8n + 3 steps: xl 99, lg 51, md 35, sm 27, xs and 2xs 19, 3xs 14px. The ink edge stays 1.5px at every size. |
type | "agent" | "human" | — | Role-keyed background: agent → stone until its sprite covers it, human → lavender. |
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.). |
...propsBase UI Avatar.Image.Props
Managed image part. Fills the frame and reveals fallback while loading or on error.
| Prop | Type | Default | Description |
|---|---|---|---|
...props | Base UI Avatar.Image.Props | — | Managed image part. Fills the frame and reveals fallback while loading or on error. |
...propsBase UI Avatar.Fallback.Props
Fallback part. Defaults to the scaled User icon when no children are passed.
| Prop | Type | Default | Description |
|---|---|---|---|
...props | Base UI Avatar.Fallback.Props | — | Fallback part. Defaults to the scaled User icon when no children are passed. |
presencedefault: "online""online" | "busy" | "error" | "offline" | "external"
The default dot's status light, from the same map as Status. Ignored when render draws its own indicator.
offset[string | number, string | number]
Where the badge's centre sits, measured from the avatar's top-left: [x, y]. Numbers are px; strings are any CSS length, and percentages are of the avatar, so ["100%", 0] is the top-right corner at every size. Omit it to keep the default bottom-right spot.
renderuseRender render prop
Optional element override. Default is the solid dot; pass render={<Status … />} for activity/presence chrome.
...propsuseRender.ComponentProps<"span">
Corner shell on the avatar. The default dot and custom renders auto-scale from the parent size.
| Prop | Type | Default | Description |
|---|---|---|---|
presence | "online" | "busy" | "error" | "offline" | "external" | "online" | The default dot's status light, from the same map as Status. Ignored when render draws its own indicator. |
offset | [string | number, string | number] | — | Where the badge's centre sits, measured from the avatar's top-left: [x, y]. Numbers are px; strings are any CSS length, and percentages are of the avatar, so ["100%", 0] is the top-right corner at every size. Omit it to keep the default bottom-right spot. |
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. |
...propsComponentProps<"div">
Overlapping avatar stack.
| Prop | Type | Default | Description |
|---|---|---|---|
...props | ComponentProps<"div"> | — | Overlapping avatar stack. |
...propsComponentProps<"span"> & { size: AvatarSize }
Trailing +N chip. Its size should match the sibling avatars.
| Prop | Type | Default | Description |
|---|---|---|---|
...props | ComponentProps<"span"> & { size: AvatarSize } | — | Trailing +N chip. Its size should match the sibling avatars. |
Source AvatarSlot was a product-specific identity slot. Current Avatar is the reusable UI primitive: it keeps the frame, 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, and badge scale from the parent size; the ink edge stays 1.5px. |
| Frame surface | Square frame with role background and black border. | Sticker frame with an ink edge; agents sit on stone, people on lavender. |
| 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 / 99px | This is a stable profile/detail scale, not a one-off layout adjustment. | Use <Avatar size="xl">; image/fallback fills the 99px 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 / 51px | 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 / 35px | 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 / 27px | 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 / 19px | Sidebar and DM rows keep their own public step on the t-shirt scale; it renders at the same 19px as xs. | Use <Avatar size="2xs"> inside SidebarItemIcon. |
| compact-list | 20px frame, 1px border | agent 18 / human 18 / icon 12 | xs / 19px | 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. |