Skip to main content

Avatar

<ui5-avatar> | Since 1.0.0-rc.6

An image-like component that has different display options for representing images and icons in different shapes and sizes, depending on the use case.

The shape can be circular or square. There are several predefined sizes, as well as an option to set a custom size.

Keyboard Handling

  • [Space] / [Enter] or [Return] - Fires the click event if the mode is set to Interactive or the deprecated interactive property is set to true.
  • [Shift] - If [Space] is pressed, pressing [Shift] releases the component without triggering the click event.

ES6 Module Import

import "@ui5/webcomponents/dist/Avatar.js";

Basic Sample

Properties

disabled

DescriptionDefines whether the component is disabled. A disabled component can't be pressed or focused, and it is not in the tab chain.
Typeboolean
Defaultfalse

interactive

DescriptionDefines if the avatar fires click events.
Note: This property only controls event firing behavior. It does not affect the component's accessibility attributes. To make the avatar interactive with proper accessibility (role="button", focusable), use mode="Interactive" instead.
Note: This property won't have effect if the disabled property is set to true.
Typeboolean
Defaultfalse
DeprecatedSince version 2.19. Use the mode property with value Interactive instead. For accessibility and visual affordance (role="button", focusable), set mode="Interactive". This property now only controls whether click events are fired.

mode

DescriptionDefines the mode of the component.
Note:
- Image (default) - renders with role="img"
- Decorative - renders with role="presentation" and aria-hidden="true", making it purely decorative
- Interactive - renders with role="button", focusable (tabindex="0"), and supports keyboard interaction
Type"Image" | "Decorative" | "Interactive"
Default"Image"
Since2.19

icon

DescriptionDefines the name of the UI5 Icon, that will be displayed.
Note: If image slot is provided, the property will be ignored.
Note: You should import the desired icon first, then use its name as "icon".
import "@ui5/webcomponents-icons/dist/{icon_name}.js"
<ui5-avatar icon="employee">
Note: If no icon or an empty one is provided, by default the "employee" icon should be displayed.
See all the available icons in the Icon Explorer.
Typestring | undefined
Defaultundefined

fallbackIcon

DescriptionDefines the name of the fallback icon, which should be displayed in the following cases:
- If the initials are not valid (more than 3 letters, unsupported languages or empty initials).
- If there are three initials and they do not fit in the shape (e.g. WWW for some of the sizes).
- If the image src is wrong.
Note: If not set, a default fallback icon "employee" is displayed.
Note: You should import the desired icon first, then use its name as "fallback-icon".
import "@ui5/webcomponents-icons/dist/{icon_name}.js"
<ui5-avatar fallback-icon="alert">
See all the available icons in the Icon Explorer.
Typestring
Default"employee"

initials

DescriptionDefines the displayed initials.
Up to three Latin letters can be displayed as initials.
Typestring | undefined
Defaultundefined

shape

DescriptionDefines the shape of the component.
Type"Circle" | "Square"
Default"Circle"

size

DescriptionDefines predefined size of the component.
Type"XS" | "S" | "M" | "L" | "XL"
Default"S"

colorScheme

DescriptionDefines the background color of the desired image. If colorScheme is set to Auto, the avatar will be displayed with the Accent6 color.
Type"Auto" | "Accent1" | "Accent2" | "Accent3" | "Accent4" | "Accent5" | "Accent6" | "Accent7" | "Accent8" | "Accent9" | "Accent10" | "Placeholder" | "Transparent"
Default"Auto"

accessibleName

DescriptionDefines the text alternative of the component. If not provided a default text alternative will be set, if present.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.7

accessibilityAttributes

DescriptionDefines the additional accessibility attributes that will be applied to the component. The following field is supported:
- hasPopup: Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by the button. Accepts the following string values: dialog, grid, listbox, menu or tree.
TypeAvatarAccessibilityAttributes
Default{}
Since2.0.0

Slots

default

DescriptionReceives the desired <img> tag
Note: If you experience flickering of the provided image, you can hide the component until it is defined with the following CSS:
ui5-avatar:not(:defined) {
    visibility: hidden;
}
TypeArray<HTMLElement>
Since1.0.0-rc.15

badge

DescriptionDefines the optional badge that will be used for visual affordance.
Note: While the slot allows for custom badges, to achieve the Fiori design, use the ui5-avatar-badge component.
TypeArray<HTMLElement>
Since1.7.0

Events

click

DescriptionFired on mouseup, space and enter if avatar is interactive
Note: The event will not be fired if the disabled property is set to true.
TypeCustomEvent
Since2.11.0
BubblesYes
CancelableNo

Methods

No methods available for this component.

CSS Parts

No CSS parts available for this component.

More Samples

Shapes

The Avatar comes in two shapes (Square and Circle).

Sizes

The Avatar comes in several sizes (S to XL).

Interactive Mode

The Avatar can be set to interactive mode with mode="Interactive", making it focusable with role="button" and enabling keyboard interaction. This is the recommended way to make an avatar interactive.

Decorative Mode

The Avatar can be set to decorative mode with mode="Decorative", making it purely visual without semantic content (role="presentation", aria-hidden="true"). This is useful when the avatar is used for visual purposes only and shouldn't be announced by screen readers.

Color Schemes

The Avatar can be displayed in multiple color schemes.

With Icon

The Avatar can show icons.

With Image

The Avatar can show images.

With Badge

The Avatar supports visual affordance through badges using the ui5-avatar-badge component. Badges can display icons with different value states to indicate status or notifications.

Custom Styling

The Avatar allows customization with pure CSS on tag level.