MUI and Chakra UI Avatar Fallback Image URLs

MUI setup

MUI Avatar fallback URL with the src and alt props

MUI's `Avatar` component renders the `src` image if it loads. If the image fails, it falls back to the `children` prop (usually initials), and then to a generic icon if children is empty. There is no direct `fallbackSrc` prop, but you can intercept the `onError` event on the underlying `img` element.

The cleanest approach is to provide a `src` that resolves to a placeholder when the real image fails. Use an `onError` handler that swaps the src to a fallback.pics avatar URL generated from the user's initials.

// MuiUserAvatar.tsx
import Avatar from '@mui/material/Avatar';
import { useRef } from 'react';

function initials(name: string) {
  return name.split(' ').map(n => n[0]).join('').slice(0, 2).toUpperCase();
}

function avatarFallback(name: string, size = 40) {
  const text = initials(name);
  return `https://fallback.pics/api/v1/avatar/${size}?text=${text}`;
}

export function UserAvatar({ src, name, size = 40 }: {
  src?: string;
  name: string;
  size?: number;
}) {
  const errored = useRef(false);

  return (
    <Avatar
      src={src}
      alt={name}
      sx={{ width: size, height: size }}
      imgProps={{
        onError: (e) => {
          if (!errored.current) {
            errored.current = true;
            (e.target as HTMLImageElement).src = avatarFallback(name, size);
          }
        },
      }}
    >
      {/* Shown if src is undefined; hidden once src loads */}
      {initials(name)}
    </Avatar>
  );
}

Chakra UI setup

Chakra Avatar fallbackSrc and getInitials props

Chakra UI's `Avatar` has a first-class `fallbackSrc` prop that accepts a URL string. When the `src` image fails, Chakra renders the `fallbackSrc` URL in an `<img>` tag automatically. No `onError` handler needed.

You can also pass `getInitials` to customize how Chakra extracts initials from the `name` prop, which controls the built-in initial-based fallback. Use `fallbackSrc` for a branded image fallback and let `getInitials` serve as a secondary text fallback if the image URL itself fails.

// ChakraUserAvatar.tsx
import { Avatar } from '@chakra-ui/react';

function avatarFallback(name: string, size = 40) {
  const text = name.split(' ').map(n => n[0]).join('').slice(0, 2).toUpperCase();
  return `https://fallback.pics/api/v1/avatar/${size}?text=${text}`;
}

export function UserAvatar({ src, name, size = 40 }: {
  src?: string;
  name: string;
  size?: number;
}) {
  return (
    <Avatar
      src={src}
      name={name}
      size="md"
      fallbackSrc={avatarFallback(name, size)}
    />
  );
}

Deterministic colors

Generating consistent avatar colors from user IDs

A deterministic color per user makes avatars instantly recognizable in lists and tables. Derive a hex color from a hash of the user's ID — not their name, which can change. Encode the color into the placeholder URL so the fallback matches the color the user would see in the initials fallback.

Use a small palette of accessible background/foreground pairs rather than arbitrary hash output. Map the hash modulo to an index in the palette array.

const PALETTE = [
  { bg: '7C3AED', fg: 'FFFFFF' }, // purple
  { bg: '0369A1', fg: 'FFFFFF' }, // blue
  { bg: '047857', fg: 'FFFFFF' }, // green
  { bg: 'B45309', fg: 'FFFFFF' }, // amber
  { bg: 'BE123C', fg: 'FFFFFF' }, // rose
];

function colorForId(id: string) {
  let hash = 0;
  for (const ch of id) hash = (hash * 31 + ch.charCodeAt(0)) >>> 0;
  return PALETTE[hash % PALETTE.length];
}

function avatarUrl(userId: string, name: string, size = 40) {
  const { bg, fg } = colorForId(userId);
  const text = name.split(' ').map(n => n[0]).join('').slice(0, 2).toUpperCase();
  return `https://fallback.pics/api/v1/avatar/${size}/${bg}/${fg}?text=${text}`;
}

List and table avatars

Applying avatar fallbacks in data tables and sidebars

Data tables that render hundreds of user rows can be slow if each avatar makes a separate fetch to probe its URL. Render the `src` directly and let the browser's native `onerror` fire for any that fail. The fallback URL is computed client-side from the user's data — no extra network requests.

In sidebars or navigation components where the logged-in user's avatar appears, use the same `avatarUrl` function with the session user's ID. This ensures the nav avatar and the table avatar for the same user always look identical.

Accessibility

Alt text and ARIA for avatar fallback images

Always set `alt` to the user's full name on avatar images. A blank `alt` makes screen readers skip the image entirely, which is appropriate for purely decorative images but not for user avatars in a team directory or comment thread.

If the avatar is inside a button or link, the accessible name should come from the button label, not the image alt. Set `alt=""` on the image in that context and ensure the button has an `aria-label`.

Further reading

More on avatar and profile image patterns

The avatar route at fallback.pics renders a circular-cropped SVG by default, matching the typical rounded avatar shape used in most component libraries.

https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/
https://fallback.pics/blog/avatar-placeholder-generator-initials-colors-accessibility/
https://fallback.pics/blog/shadcn-avatar-fallback-src/