Mushilu-San UI

Search components

PlaygroundStorybookGitHub
Primitives

Avatar

Shows a user image, or their initials when no image is available.

Selector: mui-avatar

Import
import { Avatar } from '@mushilu-san/ui/primitives';
PreviewCode

Loading example…

Overview

Avatar renders an image when src is set and loads. If the image is missing or fails to load, it falls back to the initials of name.

The host is the accessible element: it has role="img" and an aria-label taken from label, or from name when label is empty. The image and initials inside are hidden from assistive technology so the name is announced once.

When to use

  • Identifying a person or account in a list, header, comment or card.
  • Showing a compact user marker next to a name.

When not to use

  • Decorative pictures with no person behind them. Use a plain image.
  • Showing status on a user. Combine with a Badge next to the avatar instead. Use Badge instead.

Examples

Sizes and shapes

Use square for organisations or products, circle for people.

PreviewCode

Loading example…

Guidelines

Do

  • Pass name even when you also pass an image, so the fallback and the accessible name stay correct.
  • Use label when the visible name is not the full name, for example "Account of Dana Levi".

Don't

  • Do not pass untrusted or unvalidated image URLs. src is sanitised by Angular, but the URL source is still your responsibility.
  • Do not use an avatar as the only way to identify a user in a dense table. Show the name as text too.

Accessibility

Roles and attributes

ElementRoleNotes
hostimgaria-label comes from label, or from name when label is empty.
image and initials—Both are aria-hidden="true", so the name is read once.
  • An avatar is not focusable. If it links somewhere, wrap it in a link and give the link the accessible name.
  • Set label when the visible text is an abbreviation or the name is not known.

API

Avatar

Selector: mui-avatar

NameTypeDefaultDescription
srcstring | undefined— Image URL. Bound via `[src]`, so Angular's built-in URL sanitizer applies (e.g. `javascript:` URLs are neutralized). Consumers remain responsible for passing trusted/validated URLs, especially user-generated ones.
namestring'' Full name. Used for the initials fallback and, when no `label` is set, the accessible name.
labelstring'' Accessible name. Overrides `name` for screen readers.
size'sm' | 'md' | 'lg' | 'xs' | 'xl''md' Avatar size: `xs` to `xl`. Default `md`.
shape'circle' | 'square''circle' Avatar shape: `circle` or `square`. Default `circle`.

CSS parts

  • ::part(root)

Tokens

  • --mui-color-surface
  • --mui-color-text
  • --mui-radius-full

Navigation

IntroductionInstallationAll componentsAvatarBadgeButtonDividerIconSpinnerCalendarCheckboxDate pickerForm fieldInputInput groupInput OTPLabelRadioSelectSliderTextareaToggleToggle groupAspect ratioContainerGridResizableScroll areaSidebarSpacerStackBreadcrumbMenubarNav linkNavigation menuPaginationTabsAlertAlert dialogDialogProgressSheetSkeletonToastAccordionCardCarouselChartEmpty stateTableTooltipTypographyBottom sheetFloating action buttonMobile navigationSwipe actionComboboxCommandContext menuDropdown menuHover cardPopover