HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
AvatarView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA person or entity, shown as an image or as their initials.StableSince 0.1.0MediaUsageimport'@fusion.dev/helix/avatar'import'@fusion.dev/helix-headless/avatar'Preview
API ReferenceRoothelix-avatarA person or entity, shown as an image or as their initials.
PropTypeDescriptionfallbackDelaynumberHow long, in milliseconds, a picture may take before the initials stand in
for it while it loads. The attribute also takes a CSS time, such as
600ms.initialsstringThe letters shown where no picture loaded, such as GH, in place of the
ones taken from name.loading"eager"|"lazy"When the browser fetches the picture: lazy waits until it is near the
screen, as an <img loading="lazy"> does, and eager fetches it at once.namestringDefault""Name of the person or entity.shape"circle"|"rounded"Whether the avatar is a circle or a rounded square.size"sm"|"md"|"lg"Edge length of the avatar.srcstringDefault""Image to show.status"error"|"loaded"|"loading"Default"loading"The image's state: loading while it is on its way, loaded once it
arrives, or error when it fails and the initials replace it. An avatar
with no src has no image to wait for, and reports error as well, since
the initials are what it shows.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)Shown when there is no usable image, in place of the initials, for an icon. Hidden from assistive technology when the avatar has a name, which the host announces.
EventTypeDescriptionerrorEventRelayed from the image when it fails.loadEventRelayed from the image once it has loaded.
PartDescriptionimageThe image, when one is loading or loaded.initialsThe initials shown when there is no usable image.
CSS PropertyDescription--avatar-background-colorFill behind the initials.--avatar-colorThe color of the initials.--avatar-font-weightThe weight of the initials.--avatar-sizeEdge length of the avatar.
Custom stateDescriptionerrorThe picture failed, or there is none, and the initials show.loadedThe picture arrived.loadingThe picture is on its way.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-avatar-groupOverlapping avatars, with a count for the ones not shown.
PropTypeDescriptionlabelstringDefault""Accessible name for the set, such as "Reviewers".maxnumberHow many avatars are shown before the rest become a count.overflowLabelstringDefault"{count, plural, one {# more: {names}} other {# more: {names}}}"What a screen reader is told the count is, with {count} for the number,
written in the locale, and {names} for the people it stands for, by each
avatar's name, listed as the locale lists. A language that needs plural
forms writes them: {count, plural, one {# osoba więcej: {names}} few {# osoby więcej: {names}} other {# osób więcej: {names}}}.
ReadTypeDescriptionavatarsHTMLElement[]The avatars, in light-DOM order. Empty on the server, which has no tree.overflownumberHow many avatars are past the limit, and so not shown.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The avatars, in the order they should be read.
PartDescriptionoverflowThe count of avatars past max, an image named by overflow-label.
CSS PropertyDescription--avatar-group-overflow-background-colorThe fill of the count of avatars past max.--avatar-group-overflow-colorThe color of the count of avatars past max.--avatar-group-overflow-font-sizeThe type size of the count of avatars past max.--avatar-group-overlapHow far each avatar sits over the one before it.--avatar-group-ring-colorColor of the ring that separates one avatar from the next.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-avatarA person or entity, shown as an image or as their initials.
PropTypeDescriptionfallbackDelaynumberHow long, in milliseconds, a picture may take before the initials stand in
for it while it loads. The attribute also takes a CSS time, such as
600ms.initialsstringThe letters shown where no picture loaded, such as GH, in place of the
ones taken from name.loading"eager"|"lazy"When the browser fetches the picture: lazy waits until it is near the
screen, as an <img loading="lazy"> does, and eager fetches it at once.namestringDefault""Name of the person or entity.srcstringDefault""Image to show.status"error"|"loaded"|"loading"Default"loading"The image's state: loading while it is on its way, loaded once it
arrives, or error when it fails and the initials replace it. An avatar
with no src has no image to wait for, and reports error as well, since
the initials are what it shows.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)Shown when there is no usable image, in place of the initials. Hidden from assistive technology when the avatar has a name, which the host announces.
EventTypeDescriptionerrorEventRelayed from the image when it fails.loadEventRelayed from the image once it has loaded.
PartDescriptionimageThe image, when one is loading or loaded.initialsThe initials shown when there is no usable image.
Custom stateDescriptionerrorThe picture failed, or there is none, and the initials show.loadedThe picture arrived.loadingThe picture is on its way.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-headless-avatar-groupOverlapping avatars, with a count for the ones not shown.
PropTypeDescriptionlabelstringDefault""Accessible name for the set, such as "Reviewers".maxnumberHow many avatars are shown before the rest become a count.overflowLabelstringDefault"{count, plural, one {# more: {names}} other {# more: {names}}}"What a screen reader is told the count is, with {count} for the number,
written in the locale, and {names} for the people it stands for, by each
avatar's name, listed as the locale lists. A language that needs plural
forms writes them: {count, plural, one {# osoba więcej: {names}} few {# osoby więcej: {names}} other {# osób więcej: {names}}}.
ReadTypeDescriptionavatarsHTMLElement[]The avatars, in light-DOM order. Empty on the server, which has no tree.overflownumberHow many avatars are past the limit, and so not shown.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The avatars, in the order they should be read.
PartDescriptionoverflowThe count of avatars past max, an image named by overflow-label.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionBroken ImageAn image that fails to load, with the initials shown in its place.EventsThe image's load and error events, relayed from inside the shadow root and heard in the capture phase.GroupOverlapping avatars, with a count for the rest.ImageThree avatars that each show a photograph set with src.PreviewInitials taken from a name, which every avatar falls back to.PreviewInitials taken from a name, which every avatar falls back to.ShapesThe two shapes, at one size so the shape is the only difference.SizesThe three sizes, from a table row to a profile.