Avatar

An image element with a fallback for representing the user.

import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';

export default function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
      <AvatarFallback>MD</AvatarFallback>
    </Avatar>
  );
}

Install

Bash

npx @madeui/cli add avatar

Usage

TSX

import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from '@/components/ui/avatar';

Composition

TSX

<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarBadge />
</Avatar>

Sizes

SMMDLG

import * as stylex from '@stylexjs/stylex';

import { space } from '@/lib/constants.stylex';

import { Avatar, AvatarFallback } from '@/components/ui/avatar';

export default function AvatarSizes() {
  return (
    <div {...stylex.props(styles.row)}>
      <Avatar size="sm">
        <AvatarFallback>SM</AvatarFallback>
      </Avatar>
      <Avatar size="md">
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>LG</AvatarFallback>
      </Avatar>
    </div>
  );
}

const styles = stylex.create({
  row: {
    alignItems: 'center',
    display: 'flex',
    flexWrap: 'wrap',
    gap: space.s2,
  },
});

Fallback

The fallback renders while the image loads — or when it fails. Always provide one.

import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';

// The fallback renders while the image loads — or when it fails.
export default function AvatarFallbackDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://example.com/broken.png" alt="Broken" />
      <AvatarFallback>UI</AvatarFallback>
    </Avatar>
  );
}

Badge

AvatarBadge anchors a status indicator to the bottom-right corner. Pass a small icon as children for something other than a plain dot.

import * as stylex from '@stylexjs/stylex';
import { Check } from 'lucide-react';

import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { space } from '@/lib/constants.stylex';
import { icon } from '@/lib/stylex-utils';

export default function AvatarBadgeDemo() {
  return (
    <div {...stylex.props(styles.row)}>
      <Avatar>
        <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
        <AvatarFallback>MD</AvatarFallback>
        <AvatarBadge />
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/github.png" alt="@github" />
        <AvatarFallback>GH</AvatarFallback>
        <AvatarBadge>
          <Check {...stylex.props(icon.xxs)} />
        </AvatarBadge>
      </Avatar>
    </div>
  );
}

const styles = stylex.create({
  row: {
    alignItems: 'center',
    display: 'flex',
    gap: space.s6,
  },
});

Group

AvatarGroup overlaps its children with a colors.background ring separating each one.

MDGHVC

import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from '@/components/ui/avatar';

export default function AvatarGroupDemo() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/github.png" alt="@github" />
        <AvatarFallback>GH</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/vercel.png" alt="@vercel" />
        <AvatarFallback>VC</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  );
}

Group count

Add an AvatarGroupCount as the last child to show a “+N” overflow indicator.

MDGH+3

import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from '@/components/ui/avatar';

export default function AvatarGroupCountDemo() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/github.png" alt="@github" />
        <AvatarFallback>GH</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}

Built on Base UI Avatar. The tables below cover the props this library adds or changes — every other prop is forwarded to the underlying Base UI part; see the Base UI Avatar API reference for the full list.

Avatar

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`
`style`	`StyleXStyles`	—	StyleX styles merged last — always win over the component’s own styles.

AvatarGroupCount

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Matches the size of the avatars in the group.
`style`	`StyleXStyles`	—	StyleX styles merged last — always win over the component’s own styles.

Styling

AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup accept style (StyleXStyles, merged last so caller overrides always win) plus all native props of the element they render.