Avatar

What it is

A small image, initials, or fallback icon that stands for a person or entity, most often at the front of a list row or beside a name. It renders with no Titan-specific decision — every visual property is whatever the underlying element defaults to. Titan has not added a wrapper, an override, or a token to it.

Live example

No Storybook story demonstrates this component. The live index at Titan’s own Chromatic deployment has no avatar entry of any kind, and there is no Avatar.stories.js in source — confirmed by listing components/core/src/components/ in the Titan checkout, where no Avatar directory exists at all. There is nothing to embed.

Exports

Titan has not written a single line of code for this component. Avatar is re-exported directly from the underlying package in src/index.js — no wrapper component, no .overrides.ts, no .stories.js, no .test.tsx, and no theme override entry for this component anywhere in the theme (confirmed by searching the entire theme directory). Every other component in this category — Badge, Card, List, Tag — has at least a theme override behind it. Avatar has none.

Export	Implementation	Props it declares	What Titan decided
`Avatar`	Re-exported directly from the underlying package, unmodified	None — the full native `AvatarProps` passes through	Nothing

Since Titan adds nothing, the real prop surface is whatever the underlying package defines, hand-confirmed from the installed package (v7.3.6) type definitions rather than from anything Titan wrote:

Prop	Type	Default	Description
`src` / `srcSet` / `sizes`	`string`	—	The image to render
`alt`	`string`	—	Alt text for the underlying `<img>`
`children`	`ReactNode`	—	Rendered when `src` is absent or fails to load
`variant`	`"circular" \| "rounded" \| "square"`	`"circular"`	The avatar’s shape
`imgProps`	`ImgHTMLAttributes`	—	Deprecated — the underlying package recommends `slotProps.img` instead
`sx`	`SxProps`	—	The only way to set size or background color; neither has a dedicated prop

A stacking helper for overlapping avatars — with an overlap and a “+N” overflow chip — is not exported by this package. Titan’s index.js exports only bare Avatar. A stacked group has to be hand-built.

Vocabulary

Term	Also called	The system uses	In code
Avatar	Profile picture, user icon, headshot	`avatar`	`Avatar`

No aliasing dispute exists here the way it does for Table or Tag — “avatar” is the word code, the design library, and casual conversation all use for this concept.

Choose Avatar when

Representing a specific person or entity as a small circular image or initials, most often beside their name in a list row, a comment, or a page header.
A photo may or may not be available, and a graceful fallback — initials via children, or a default icon — is acceptable.

Choose something else when

If you need to…	Use	Why
Layer a small count or status dot onto another element	Badge	Avatar represents an identity; Badge overlays a status onto whatever it wraps — including onto an Avatar itself, per Badge’s own published story.
Label an attribute, category, or status	Tag	A Tag names a property of a record. An avatar names who — a specific identity, not an attribute.
Show a small square or rounded thumbnail of non-person content — a document, a logo, a media placeholder	Avatar’s own `variant="rounded"` or `"square"`	Avatar already covers all three shapes; there is no separate “thumbnail” component to reach for instead.
Stack several avatars to represent a group of people	Nothing shipped — build it by hand	A stacking helper exists in the underlying element but Titan’s package does not export it — see Known issues.

Anatomy

#	Part	Prop	Required
1	Image	`src` (with `srcSet`, `sizes`, `alt`)	No
2	Fallback content	`children`	No — renders only once no image is loading or available
3	Default fallback icon	None — automatic	No — renders only when neither `src` nor `children` is usable

The three fall back in that order: image, then children, then a default icon. Confirmed by reading the underlying element’s own source — the default icon is an internal Person SVG built into the package, not one of Titan’s own Icons.* set. Titan has not swapped it for anything of its own.

Variants, sizes, and states

Titan applies no theme entry, so everything below is an unthemed default with no Titan decision behind it — hand-confirmed against the installed package (v7.3.6), not emitted from any Titan source.

Axis	Values
Shape (`variant`)	`circular` (default), `rounded`, `square`
Size	Fixed at 40×40px. No size prop exists — set `width`/`height` via `sx` by hand.
Color	No `color` prop. The fallback background is `theme.palette.grey[400]` in light mode and `grey[600]` in dark, straight from the underlying package’s default theme — not a Titan token.
States	None. Avatar is not a control — it has no hover, focus, disabled, or pressed state.

Edge and failure states

Condition	What happens	What to do
`src` fails to load	Falls back to `children` if present, otherwise the default Person icon	Always supply `children` (typically initials) so a failed image never surfaces a generic silhouette that means nothing to the reader
No `src` and no `children`	Renders the default Person icon on the unthemed grey background	Supply initials via `children` — an anonymous icon in a product surface signals nothing about who the row belongs to
Long text passed as `children`	Undefined — no story or test in the Titan checkout exercises this, since none exists	Keep `children` to one or two characters; the underlying element does not scale or truncate text to fit the circle

Tokens

No Titan token, override, or theme entry exists for Avatar — confirmed by searching the entire theme directory for a theme override entry for this component and finding nothing. Every value below is an unthemed default with no Titan decision behind it, hand-confirmed from the installed package, not from any Titan file.

Value	Source
40×40px box	The underlying element’s own default styles
`theme.palette.grey[400]` (light) / `grey[600]` (dark)	Fallback background, from the underlying package’s default theme, not a Titan token
`theme.palette.background.default`	Fallback icon/text color
`variant="circular"`	The underlying element’s default shape

Composition

Sits inline in a row — a list item’s leading slot, a table cell, a comment header, or beside a name in a page header. List’s own List.overrides.ts themes the list-item-icon slot but has no override entry for a list-item avatar slot either — so an Avatar placed in a list row’s leading slot renders at the underlying element’s own spacing, not a value Titan chose.

Content

Avatar carries no visible label copy of its own beyond alt and children:

alt should name the person or entity the image represents — “Photo of Jordan Diaz,” not “avatar” or “user image.”
children used as an initials fallback should be one or two characters, drawn from the same name as alt.

Accessibility

No role or accessible-name handling is added by Titan — whatever alt a caller supplies on the underlying <img> is what a screen reader gets. Nothing in source enforces that one exists.
Unconfirmed: whether the default Person fallback icon is marked aria-hidden. Since Titan has not touched Avatar at all, this is entirely upstream behavior from the underlying package that this page has not independently verified against the installed version’s rendered DOM.
This component does not decide whether identifying a person by photo or initials is appropriate for the surface it appears in — that is a per-page content and privacy decision.

Constraints

ID	Constraint	Rationale
TITAN-AVT-01	Always supply `alt` (for an image) or meaningful `children` (for initials) — never leave an Avatar with neither identifying who or what it represents.	The unthemed default fallback is a generic Person icon carrying no information about the specific record; a page relying on it renders every missing avatar identically.
TITAN-AVT-02	Use Badge to convey a status or count on an Avatar — never build one by hand on top of it.	Badge already exists with the `anchorOrigin`/`overlap` handling this would otherwise duplicate, and its own published story demonstrates layering onto a circular shape.

Known issues

Avatar: open issues

Divergences, open decisions, and undocumented gaps for Avatar.

Why it works this way

There is no Titan decision to explain here, and this page says so rather than inventing one. Badge, Card, and List — the other three components in this category with a real Titan source file behind them — each carry a .overrides.ts translating at least one slot of the underlying element into a theme.vars.tokens[…] value. Avatar has none. Whether that is a considered decision — avatars are always left at the underlying package’s defaults across Invoca products — or simply an oversight is not recorded anywhere this session could find. See Known issues.

Status

Package @invoca/titan-core, version 3.6.3. Export: Avatar, re-exported unmodified from the underlying package. There is no dedicated Titan source file, so no independent version history, deprecation marker, or since field exists for it beyond the package’s own release notes. No utilization data exists for Avatar specifically. utilization.md is generated per Titan component directory in the checkout, and Avatar has none to hold one. Real usage of Avatar certainly exists across Invoca products — it is a normal export available to every consumer of the package — but it is not tracked the way every other component in this category is.

Badge — for overlaying a status or count, including on top of an Avatar
List — the most common place an Avatar sits, in a row’s leading slot
Card — often carries an Avatar near a name in its header area

Overview

Actions

Forms

Data display

Navigation

Feedback

Containment

What it is

Live example

Exports

Vocabulary

Choose Avatar when

Choose something else when

Anatomy

Variants, sizes, and states

Edge and failure states

Tokens

Composition

Content

Accessibility

Constraints

Known issues

Avatar: open issues

Why it works this way

Status

​What it is

​Live example

​Exports

​Vocabulary

​Choose Avatar when

​Choose something else when

​Anatomy

​Variants, sizes, and states

​Edge and failure states

​Tokens

​Composition

​Content

​Accessibility

​Constraints

​Known issues

Avatar: open issues

​Why it works this way

​Status

​Related

What it is

Live example

Exports

Vocabulary

Choose Avatar when

Choose something else when

Anatomy

Variants, sizes, and states

Edge and failure states

Tokens

Composition

Content

Accessibility

Constraints

Known issues

Why it works this way

Status

Related