Avatar

A visual representation of a user or team.

Sizes

sm is 24px, the default is 32px, and lg is 40px.

ACACAC

import { Avatar, AvatarFallback } from "@smallest-inc/ui";

export default function AvatarSizes() {
  return (
    <div className="flex items-center gap-3">
      <Avatar size="sm">
        <AvatarFallback>AC</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>AC</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>AC</AvatarFallback>
      </Avatar>
    </div>
  );
}

Image

AvatarImage loads the photo. AvatarFallback shows initials until it loads, or instead of it when it fails.

DPRG

import { Avatar, AvatarFallback, AvatarImage } from "@smallest-inc/ui";

export default function AvatarWithImage() {
  return (
    <div className="flex items-center gap-3">
      <Avatar size="lg">
        <AvatarImage src="/docs/devansh-avatar.png" alt="Devansh Pawan" />
        <AvatarFallback>DP</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="/missing-avatar.png" alt="Riley Gupta" />
        <AvatarFallback>RG</AvatarFallback>
      </Avatar>
    </div>
  );
}

Badge

AvatarBadge marks presence in the bottom-right corner and scales with the avatar.

JLJLJL

import { Avatar, AvatarBadge, AvatarFallback } from "@smallest-inc/ui";

export default function AvatarWithBadge() {
  return (
    <div className="flex items-center gap-3">
      <Avatar size="sm">
        <AvatarFallback>JL</AvatarFallback>
        <AvatarBadge>
          <span className="sr-only">Online</span>
        </AvatarBadge>
      </Avatar>
      <Avatar>
        <AvatarFallback>JL</AvatarFallback>
        <AvatarBadge>
          <span className="sr-only">Online</span>
        </AvatarBadge>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>JL</AvatarFallback>
        <AvatarBadge>
          <span className="sr-only">Online</span>
        </AvatarBadge>
      </Avatar>
    </div>
  );
}

Group

AvatarGroup overlaps members by 8px with a white ring. End with AvatarGroupCount when the set is truncated; it matches the group's size.

ACJLRG

ACJLRGCK

import { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount } from "@smallest-inc/ui";

const reviewers = ["AC", "JL", "RG", "CK"];

export default function AvatarGroupExample() {
  return (
    <div className="flex flex-col items-start gap-4">
      <AvatarGroup role="group" aria-label="3 reviewers">
        {reviewers.slice(0, 3).map((initials) => (
          <Avatar key={initials}>
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
      </AvatarGroup>
      <AvatarGroup role="group" aria-label="6 reviewers">
        {reviewers.map((initials) => (
          <Avatar key={initials}>
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
        <AvatarGroupCount>+2</AvatarGroupCount>
      </AvatarGroup>
      <AvatarGroup role="group" aria-label="6 reviewers">
        {reviewers.map((initials) => (
          <Avatar key={initials} size="sm">
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
        <AvatarGroupCount>+2</AvatarGroupCount>
      </AvatarGroup>
    </div>
  );
}

Stacking order

The first member sits on top by default. Set reverse so the last member sits on top; left-to-right order stays the same.

ACJLRG

import { Avatar, AvatarFallback, AvatarGroup } from "@smallest-inc/ui";

const members = ["AC", "JL", "RG"];

export default function AvatarStackingOrder() {
  return (
    <div className="flex items-center gap-8">
      <AvatarGroup>
        {members.map((initials) => (
          <Avatar key={initials}>
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
      </AvatarGroup>
      <AvatarGroup reverse>
        {members.map((initials) => (
          <Avatar key={initials}>
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
      </AvatarGroup>
    </div>
  );
}

Best practices

When to use

Use to identify a person, team, integration or agent where recognition speeds up scanning.
Use an icon when the subject is a capability or action rather than an identity.

Behavior

Sizes: sm 24px for dense rows and notifications, default 32px, lg 40px for Entity media.
Always include AvatarFallback with initials; it shows while AvatarImage loads and when it fails.
AvatarBadge marks presence and scales with the avatar. Don't use it for counts.
AvatarGroup overlaps members by 8px with a white ring. Show at most four, then AvatarGroupCount ("+2"). Set reverse when the last member should sit on top.

Content

Initials are one or two uppercase letters from the display name.

Accessibility

Give AvatarImage meaningful alt text when it's the only name on screen; use alt="" when the name is next to it.
Label groups with the total (role="group" aria-label="6 reviewers"). Pair AvatarBadge with sr-only text such as "Online".

PreviousAperture NextBreadcrumb