Avatar

Displays a user image, initials, or icon in a consistently sized container. Supports three shapes, four preset sizes, an optional ring outline, and automatic image-error fallback. All styles derive from theme tokens.

Image source priority

src and srcSet are the primary source (srcSet serves as responsive variants alongside src, not a separate fallback step). When the primary source fails, the component advances to fallback, then to children.

src (+ srcSet) → fallback → children

When only srcSet is provided (no src), it becomes the primary source.

Examples

With Image

<Avatar
  src="/soroush.svg"
  alt="Soroush logo"
  variant="circular"
  size="md"
  ring={false}
/>

Fallback Image

<Avatar
  fallback="/soroush.svg"
  alt="Fallback image"
  variant="circular"
  size="md"
  ring={false}
/>

Fallback Initials

<Avatar variant="circular" size="md" ring={false} bg="secondary">MS</Avatar>

All Variants

circular

rounded

square

<Flex flexDirection="row" gap={3} alignItems="center">
  {(['circular', 'rounded', 'square'] as const).map((v) => (
    <Flex key={v} alignItems="center" gap={1}>
      <Avatar variant={v} size="lg" bg="secondary">
        MS
      </Avatar>
      <Typography variant="caption" color="secondary" m={0}>
        {v}
      </Typography>
    </Flex>
  ))}
</Flex>

All Sizes

<Flex flexDirection="row" gap={3} alignItems="flex-end">
  {(['sm', 'md', 'lg', 'xl'] as const).map((s) => (
    <Flex key={s} alignItems="center" gap={1}>
      <Avatar size={s} bg="secondary">
        MS
      </Avatar>
      <Typography variant="caption" color="secondary" m={0}>
        {s}
      </Typography>
    </Flex>
  ))}
</Flex>

With Ring

<Avatar
  src="/soroush.svg"
  alt="Soroush logo"
  variant="circular"
  size="lg"
  ring
/>

Ring Shapes

circular

rounded

square

<Flex flexDirection="row" gap={4} alignItems="center">
  {(['circular', 'rounded', 'square'] as const).map((v) => (
    <Flex key={v} alignItems="center" gap={1}>
      <Avatar ring variant={v} size="lg" bg="secondary">
        MS
      </Avatar>
      <Typography variant="caption" color="secondary" m={0}>
        {v}
      </Typography>
    </Flex>
  ))}
</Flex>

Ring Variants

light

primary

dark

<Flex flexDirection="row" gap={4} alignItems="center">
  {(['light', 'primary', 'dark'] as const).map((c) => (
    <Flex key={c} alignItems="center" gap={1}>
      <Avatar ring ringColor={c} size="lg" bg="secondary">
        MS
      </Avatar>
      <Typography variant="caption" color="secondary" m={0}>
        {c}
      </Typography>
    </Flex>
  ))}
</Flex>

Avatar API reference