Avatar
Avatar is a circular badge that identifies a person or entity with a photo, an icon or initials. When several sources
are set, it shows the first available in the order imgSrc, icon, label.Typography & Media
When to use
Use when
- Headers, menus, comments or list rows need to identify a person or entity.
- You want a photo with an icon or initials fallback, without your own branching.
Avoid when
- The avatar is an action — use
IconButton. - The image is editorial (cover, banner) — use
Image. - You need a status badge;
Avatarhas no badge slot — compose it withStatusDot.
Usage
G
import { Avatar } from '@apollion-dsi/core/elements/avatar';
import { user } from '@apollion-dsi/core/icons';
<Avatar size="large" imgSrc={photoUrl} alt="Ana Souza" />
<Avatar size="large" icon={user} />
<Avatar size="large" label="G" />icon takes icon data from @apollion-dsi/core/icons. label renders in uppercase; in the medium, large and
extraLarge sizes a single character is set larger. The photo is cropped to the circle.
Sizes
size is small, medium (default), large, extraLarge or giant. The circle and its initials are sized on the
text-size axis, so the whole avatar grows with the app's textSize.
Accessibility
- Photo: pass
altwith the person's name; it reaches the<img>. Withoutaltthe image getsalt=""and is treated as decorative — right when the name is already in adjacent text. - Initials: the container gets
role="img"andaria-label={alt ?? label}. Passaltto announce the full name instead of the initials. - Icon: no accessible name is set; pair the avatar with visible text.
Properties
Name
Type
Default
Description
alignContent"center""start""end""between""around""evenly""stretch"nonePacking of wrapped lines / grid tracks on the block axis.
altstringnoneAccessible name — the image's `alt` (with `imgSrc`) or the container's
`aria-label` (with initials). Omit for a decorative avatar.
@example ```tsx
<Avatar imgSrc={photoUrl} alt="Fernando Barros" />
<Avatar label="FB" alt="Fernando Barros" />
```
containmentstringnoneContainment marker for the `cq` channel: emits
`container-type` (+ `container-name` when the string form carries one,
e.g. `'inline-size card'`). Apply on the immediate wrapper of the
adapting component — NEVER on page-level shells.
cqPartial<Record<ContainerSizeTypes, Partial<Omit<Partial<{ area: string; padding: stringnumber; margin: stringnumber; isHidden: boolean; truncate: boolean; lineClamp: number; pageShell: boolean; ... 14 more ...; transform: string; }>, "containment"> & Partial<...> & SizeFactoryProps & Partial<...>>>>noneContainer-relative **layout** styles per `theme.containerSizes` key.
enableBreakpoint"xs""xl""sm""md""lg"noneForces a breakpoint's prop set to apply regardless of viewport (stories/previews).
iconIconDatanoneName of the icon (from the set supported by `Icon`) displayed when `imgSrc`
is not provided. Takes precedence over `label`.
@see {@link IconProps.name } for the list of available icons.
ignoreResponsivebooleannoneFully disables the responsive factory (tests / fixed snapshots).
imgSrcstringnoneURL of the image to display. Takes precedence over `icon` and `label`.
@example ```tsx
<Avatar imgSrc="https://i.pravatar.cc/120" />
```
justifyItems"center""start""end""stretch"noneGrid containers: inline alignment of every item in its cell.
labelstringnoneText displayed when neither `imgSrc` nor `icon` is provided. Commonly
used with the user's initials; rendered in uppercase.
@example ```tsx
<Avatar label="FB" />
```
legibility"on-photo"noneReading-shadow preset for text over a photographic background
(`on-photo`). Replaces the inline `style={{ textShadow }}` in the
consumer (brasil_2030 radar, gap A3). Token emission is deferred until a
2nd consumer asks for the raw var (see backlog).
lineClampnumbernoneCaps the text at this many lines and ends the cut with an ellipsis.
The full string stays in the DOM.
pageShellbooleannoneCenters the element and caps the width at `theme.layout.pageMaxWidth`.
The page shell of a classic centered layout.
placeItems"center""start""end""stretch"noneGrid containers: `place-items` shorthand (block + inline).
readablenumberbooleannoneMakes the `color` legible against the page surface: `true` = WCAG AA
(4.5), a number sets a custom floor. Ignored with `contrast`.
See the Layout Props concept page for the full semantics.
size"small""medium""large""giant""extraLarge"'medium'Size of the avatar. Controls width, height, and the `label` font size.
transformstringnoneCSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks
to the DOM as an attribute.
viewportMediasPartial<Record<keyof BreakPoint<any>, Partial<Omit<Partial<{ area: string; padding: stringnumber; margin: stringnumber; isHidden: boolean; truncate: boolean; lineClamp: number; pageShell: boolean; ... 14 more ...; transform: string; }>, "containment"> & Partial<...> & SizeFactoryProps & Partial<...>>>>undef...noneViewport-driven **layout** styles per `theme.breakpoints` key.