Avatar

Circular visual representation of a user or entity. Accepts an image, icon or text and automatically picks the first one available in the order imgSrc > icon > label.

It is built on top of Flex and inherits the layout props, so it can be positioned in grids/flexbox without extra wrappers.

import { Avatar } from '@apollion-dsi/core/elements/avatar';
import { trash, user } from '@apollion-dsi/core/icons';
 
const Example = () => <Avatar label="G" />;

When to use

✅ Use when…	🚫 Avoid when…
In headers, user menus and lists to identify the person or entity associated with a row/action. In chips, comments and cards where visual identity is an essential part of the information. When you want a graceful fallback between photo → icon → initials without having to orchestrate that logic outside the component.	As an action button. Use `IconButton` — `Avatar` is purely decorative/identity-focused and does not communicate click affordance. For large images in editorial contexts (covers, banners). Use `Image` with native proportions. As a status indicator (standalone online/offline). Combine it with an external badge; `Avatar` does not provide that slot.

Variations

The Avatar component can be used in different ways, through the imgSrc, icon or label properties.

<Flex mb="xl" gap="large" flexDirection="row" wrap="wrap">
  <Avatar size="large" imgSrc="https://example.com/photo.jpg" />
  <Avatar size="large" icon={trash} />
  <Avatar size="large" label="G" />
</Flex>

Precedence between sources

If more than one source is provided, the image takes precedence over the icon, which takes precedence over the label. Useful for flows where the photo may still be loading and you want a graceful fallback:

<Avatar imgSrc={user.photoUrl} icon={user} label={user.initials} />

Interactive Demo

imgSrc

label

icon

Properties


Prop	Type	Default	Description
`alignContent`	`"center" \| "start" \| "end" \| "between" \| "around" \| "evenly" \| "stretch"`	—	Packing of wrapped lines / grid tracks on the block axis.
`alt`	`string`	—	Accessible 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" /> ```
`containment`	`string`	—	Containment 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.
`cq`	`Partial<Record<ContainerSizeTypes, Partial<Omit<Partial<{ area: string; padding: string \| number; margin: string \| number; isHidden: boolean; truncate: boolean; pageShell: boolean; ... 14 more ...; transform: string; }>, "containment"> & Partial<...> & SizeFactoryProps & Partial<...>>>>`	—	Container-relative layout styles per `theme.containerSizes` key.
`enableBreakpoint`	`"xs" \| "xl" \| "sm" \| "md" \| "lg"`	—	Forces a breakpoint's prop set to apply regardless of viewport (stories/previews).
`icon`	`IconData`	—	Name 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.
`ignoreResponsive`	`boolean`	—	Fully disables the responsive factory (tests / fixed snapshots).
`imgSrc`	`string`	—	URL 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"`	—	Grid containers: inline alignment of every item in its cell.
`label`	`string`	—	Text 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"`	—	Reading-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).
`pageShell`	`boolean`	—	Centers the element and caps the width at `theme.layout.pageMaxWidth`. The page shell of a classic centered layout.
`placeItems`	`"center" \| "start" \| "end" \| "stretch"`	—	Grid containers: `place-items` shorthand (block + inline).
`readable`	`number \| boolean`	—	Makes 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.
`transform`	`string`	—	CSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks to the DOM as an attribute.
`viewportMedias`	`Partial<Record<keyof BreakPoint<any>, Partial<Omit<Partial<{ area: string; padding: string \| number; margin: string \| number; isHidden: boolean; truncate: boolean; pageShell: boolean; container: boolean; ... 13 more ...; transform: string; }>, "containment"> & Partial<...> & SizeFactoryProps & Partial<...>>>> \| unde...`	—	Viewport-driven layout styles per `theme.breakpoints` key.

Besides the props above, every component accepts the layout props (spacing, color, flex/grid, sizing, border) — not repeated here.

Accessibility

The accessible-name pattern (A14, WCAG image-alt / aria-prohibited-attr):

Photo avatar — pass alt with the person's name: it is forwarded to the inner <img>. Omit it for decorative avatars (name already adjacent in text): the image then emits alt="", which passes audits silently.
Initials avatar — the container exposes role="img" with aria-label={alt ?? label} automatically; pass alt for a proper name instead of the raw initials.
The label prop is a sizing/content input only — it never reaches the DOM as an attribute.

<Avatar imgSrc={photoUrl} alt="Fernando Barros" />
<Avatar label="FB" alt="Fernando Barros" />
<Avatar imgSrc={decorativeUrl} /> {/* alt="" — decorative */}