alt names the person for assistive technology and fallback holds the initials shown until the image loads, or when it fails. Always set a fallback: images can be missing, slow or blocked.
Fallback
Fallbacks
Default density
Compact density
Restart from the initial state
Show the copyable source
A broken src falls back without flashing. Default-slot content replaces the fallback text when initials don’t fit, such as an icon for an organization. Use fallback-delay to avoid a brief flash of initials on fast connections. Changing the image source after an error retries loading. A fallback already shown is not hidden by a later delay change. keep-mounted preserves the native image for lazy loading; while unavailable it is visually and accessibility hidden, with fallback active.
Sizes
Sizes
Default density
Compact density
Restart from the initial state
Show the copyable source
The badge grows to hold a small icon, which works for marks like verified or an add action. It still needs its own name. Small avatars hide the icon while retaining the badge’s accessible status name.
Groups
Group with overflow
Default density
Compact density
Restart from the initial state
Show the copyable source
tp-avatar-group overlaps its avatars and, with omitted, ends with a named count of the people not shown. The group’s size sets the count’s size; each avatar keeps its own. Logical overlap supports RTL.
Icon count in an empty state
Default density
Compact density
Restart from the initial state
Show the copyable source
Resend invites
Resend invites
<tp-empty-state title="Nobody has joined yet" description="Maya, Daniel and Amara were invited to Q3 planning, along with three others.">
<tp-avatar-group slot="media" id="avatar-icon-count" size="lg" omitted="3">
<tp-avatar size="lg" src="https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=96&h=96&fit=crop" fallback="MC" alt="Maya Chen"></tp-avatar>
<tp-avatar size="lg" src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=96&h=96&fit=crop" fallback="DK" alt="Daniel Kim"></tp-avatar>
<tp-avatar size="lg" src="https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=96&h=96&fit=crop" fallback="AO" alt="Amara Okafor"></tp-avatar>
</tp-avatar-group>
<tp-button slot="actions" variant="outline">Resend invites</tp-button>
</tp-empty-state>
<script type="module">
import { html } from 'lit';
await customElements.whenDefined('tp-avatar-group');
document.querySelector('#avatar-icon-count').partContracts = {
'avatar-overflow-count': {
content: html`<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>`,
},
};
</script>
The avatar-overflow-count part can render an icon in place of the number through partContracts. It still announces the three people who aren’t shown.
Shape and grayscale
Custom shape and grayscale
Default density
Compact density
Restart from the initial state
Show the copyable source
A border-radius on the avatar reshapes the image and the fallback alike, which suits companies and workspaces. partPresentation styles the avatar-image part alone, so a grayscale filter, for example for people who have left, leaves fallbacks and badges in color.
Beside a name
Decorative avatar
Default density
Compact density
Restart from the initial state
Show the copyable source
When a visible name sits next to the avatar, mark the avatar aria-hidden="true" so screen readers don’t announce the person twice.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptionsrcsrcstring''The image URL.altaltstring''The person's or entity's name for assistive technology, used by the image and the fallback.fallbackfallbackstring''Text shown while the image is unavailable, usually initials.sizesize'sm' | 'default' | 'lg''default'The avatar's size.fallback-delayfallbackDelaynumber0Milliseconds to wait before showing the fallback, so a fast image load does not flash it.keep-mountedkeepMountedbooleanfalseRenders the image before it has loaded, so the browser's own lazy loading applies.loadingloading'eager' | 'lazy''eager'The image's loading strategy; lazy takes effect with keep-mounted.srcsetsrcSetstring''Responsive image candidates, as on a native image.sizessizesstring''The image's display sizes for choosing among srcset candidates.crossorigincrossOrigin'' | 'anonymous' | 'use-credentials'''The image request's CORS mode.referrerpolicyreferrerPolicyReferrerPolicy''The referrer policy of the image request.
Properties
PropertyTypeDefaultDescriptiononLoadingStatusChange((status: AvatarLoadingStatus) => void) | undefined—Called with each new loading status, as an alternative to listening for the event.imageLoadingStatusread-onlyAvatarLoadingStatus—The current image's loading status.
Events
EventTypeDescriptiontp-loading-status-changeCustomEvent<{ status: ImageLoadStatus; }>The image's loading status changed; detail.status is the new status.
Slots
SlotDescriptiondefaultFallback content that replaces the fallback text, such as an icon for an organization.badgeA status mark on the avatar's edge; give it a text name, since color alone says nothing.
CSS parts
PartDescription::part(avatar-badge)The enclosure of the status mark on the avatar's edge.::part(avatar-fallback)The fallback shown while the image is unavailable.::part(avatar-image)The image.
<tp-avatar-group>
Attributes
AttributePropertyTypeDefaultDescriptionsizesize'sm' | 'default' | 'lg''default'The size of the omitted count; each avatar keeps its own size.omittedomittednumber0How many people the group leaves out, shown as a named count after the avatars.
Slots
SlotDescriptiondefaultThe avatars.
CSS parts
PartDescription::part(avatar-group)The row that overlaps the avatars.::part(avatar-overflow-count)The avatar that counts the people the group leaves out.
Related
Components, widgets and patterns that use this one.