Avatar

A user or organization image, shown as a circle or a square.

CircleS

SquareS

1<template>2  <Avatar shape="Circle" size="sm" />3</template>

Props

Use shape="Circle" (the default) for real user avatars - it's what UAvatar renders out of the box.
Reach for shape="Square" only where the surrounding layout is already square-cornered (dense tables, integration lists) - Circle is the default everywhere else.

Don't mix shapes within the same list of avatars (e.g. an AvatarGroup) - pick one shape per context.

An overlapping stack of avatars.

CBA

1<template>2  <UAvatarGroup>3    <Avatar alt="A" />4    <Avatar alt="B" />5    <Avatar alt="C" />6  </UAvatarGroup>7</template>

An avatar paired with a name, and an optional subtitle and status badge.

Subtitle + badge

Shadcn

Status

Pro plan

Small size

Shadcn

1<template>2  <LabeledAvatar name="Shadcn" subtitle="Pro plan" :badge="true" />3</template>

Use the default size wherever there's room for a name and secondary line (account menus, member lists) - the badge prop is meant for a lightweight status flag like "Owner" or "Invited", not for arbitrary content.
Use sm for dense contexts (comment threads, activity feeds) where only the name matters.
Pass src when you have a real avatar image; omit it to fall back to initials via UAvatar.

Don't show subtitle or badge at size="sm" - the component doesn't render them there on purpose, since there's no room and it would crowd the row. Use size="default" instead if you need that context.
Don't use this for a bare avatar with no accompanying text - use UAvatar directly.