Skip to content
Components

Avatar

Container for a user or entity avatar; compose an AvatarImage and AvatarFallback inside, and the fallback shows automatically when the image is missing or fails to load.

MR

Usage

import { Avatar, AVATAR_SIZE_CLASS, AVATAR_SIZE_PX, AvatarBadge, AvatarExtendedSize, AvatarFallback, AvatarGroup, AvatarGroupVariant, AvatarImage, AvatarSize, AvatarStatus } from "@instruments/materia-ui/components/avatar";

Best practices

  • Always render an AvatarFallback child - it is what shows while the image loads and when src is missing or errors; an image-only avatar renders empty on failure.

  • Give AvatarImage a meaningful alt; the visual is decorative only when the fallback initials already convey the identity.

  • Keep the default radius="full" for people; use a squared radius for brand/entity logos so they read as objects, not users.

Props

Avatar

PropTypeDefaultDescription
sizeAvatarSize | undefined"base"
radius"rounded" | "square" | "full" | undefined

Border radius. Defaults to "full" (circular).

withRingboolean | undefinedfalse

Show a decorative ring around the avatar.

ringColorstring | undefined"ring-primary"

Tailwind ring-* utility for the ring; only applies when withRing.

AvatarBadge

PropTypeDefaultDescription
classNamestring

CSS class name

countnumber

Number shown in the badge; hidden when 0 or omitted unless dot is set.

dotboolean | "neutral" | "brand" | "danger" | "warning" | "success" | "info"false

Render a plain dot instead of a number. true tints it with the badge's own tone; a {@link Tone} value overrides that with the shared dot tint.

maxnumber99

Cap above which the count renders as {max}+.

position"bottom-right" | "top-right" | "bottom-left" | "top-left""top-right"
size"base" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl"

Component size

toneAvatarBadgeTone"danger"

Semantic fill tone.

AvatarFallback

PropTypeDefaultDescription
styleReact.CSSProperties | undefined

Inline styles merged over the derived colours; a plain object only.

sizeAvatarSize | undefined"base"
namestring | undefined

Full name or label used to: - Derive 1–2 letter initials for fallback text (when children not provided) - Seed deterministic background/text colour for readability

AvatarGroup

PropTypeDefaultDescription
animateboolean | undefined

Enable hover animation

avatars(required)readonly ReactNode[]

The avatars to show, in order. Every avatar takes the group's size through context, so pass plain <Avatar> elements with a key.

classNamestring | undefined

CSS class name

labelsstring[] | undefined

Accessibility labels for each avatar

maxnumber | undefined

Maximum number of avatars to display before showing surplus

onSelect((index: number) => void) | undefined

Selection change handler

renderSurplus((count: number) => ReactNode) | undefined

Custom render function for surplus count

selectableboolean | undefined

Enable avatar selection

selectedIndexnumber | undefined

Selected avatar index

sizenumber | "base" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl" | undefined"base"

Size as a ComponentSize token, or an explicit pixel number.

spacing"normal" | "tight" | "loose" | undefined

Spacing between avatars

variantAvatarGroupVariant | undefined

Visual variant - controls borders and surplus styling

AvatarImage

PropTypeDefaultDescription
alt(required)string

Accessible alt text describing the avatar. Required for screen readers.

AvatarStatus

PropTypeDefaultDescription
classNamestring

CSS class name

position"bottom-right" | "top-right" | "bottom-left" | "top-left""bottom-right"
size"base" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl"

Component size

status(required)AvatarStatusType
withBorderbooleantrue

Ring separating the dot from the avatar.

Also exports

  • constAVATAR_SIZE_CLASS
  • constAVATAR_SIZE_PX
  • typeAvatarExtendedSize
  • typeAvatarGroupVariant
  • typeAvatarSize

Composition

Builds on

Center, Dot, Flex, VisuallyHidden

Used by

MobileNavigationRoot