Intro

Avatars are visual representations of users, products, or business entities, helping people quickly identify them within an application. Users can be shown with their own photos or initials, while products can be depicted with representative images or logos.

Examples of a user image, user initials, and standard user placeholder icon

Component availability

This component is available in the following libraries:

When to Use

Anatomy

Types

Content types

Avatars represent people, products, or business objects, and can display a photo, initials, or a placeholder icon.

A: User photo or business image
B: User’s initials
C: Placeholder icon

Avatar types

Images

Use images for avatars when representing people or business content. Avatars can display either user or business images.

The avatar component can be configured in various shapes. For more information on the shape types and their usage, see the Shape Types section.

Optimize high-resolution images to avoid unnecessarily large files. Large image files can severely impede page performance.

The examples below show square avatars for business content.

Examples of business images

Initials

The initials stand for the first and last name of a person – for example, JD for Jane Doe, or MvV for Marjolein van Veen. The order of the initials depends on the language – for example, first name before last name in English.

Initials can have up to three alphabetical characters (A-Z, a-z). If more than 3 initials are required for longer names (such as Anna María Agustí Suárez), the gender-neutral placeholder icon is displayed instead. The placeholder is also used if the three letters don’t fit into the circle (for example, WWW).

User initials with 1, 2, and 3 characters

Placeholder icons

Placeholder icons are used for both user and business images when no other image is available:

• The default placeholder for a user is a gender-neutral person icon inside a circle.
• The default placeholder for other images is a neutral product icon inside a square.

Default person and product placeholders

You can specify your own default placeholder icon for business images. Always replace the default product icon if there is a more suitable icon for your use case and industry.

Product placeholders with custom icons

Background color

The background color is set to blue by default. However, to add more visual variety to the UI, you can change the background color using one of the following options:

• Avatar colors: You can specify one of 10 different avatar colors as the placeholder background color.
• Random color: The component automatically picks a random color from the avatar color palette.

All avatar colors can be themed.

User initials in all 10 accent colors

For images in the content area, use the background color “placeholder” to keep the primary focus on the text. This approach ensures that image content plays a secondary role.

Image and placeholder icon with background color “placeholder”

You can use images with transparent backgrounds to display descriptive illustrations and visuals.

Images with transparent backgrounds

You can use the avatar component to display icons as non-interactive elements. To do this, apply the background color “placeholder”.

Don’t use icons as images. Icons are usually part of an icon font.

Don’t apply actions to icons. If you want to place an action on the icon, use the button with an icon inside instead.

Icon examples with background color “placeholder”

Interaction types

From an interaction standpoint, an avatar can be one of two types:

• Interactive: Focusable and pressable. Interactive avatars can display a badge.
• Non-interactive: Not focusable and not pressable.

Users can press or click an interactive avatar to trigger an action.

Interactive avatar (A) and non-interactive avatar (B)

If the avatar is interactive, you can display a badge with an icon. The badge signals that the avatar is interactive, and the icon indicates the action that will be triggered. This is especially useful for images.

Avoid badges on avatars smaller than size S to preserve visibility. Always include a tooltip that describes the action.

Avatars with badges for zoom in (left), edit (center), and change picture (right)

Shape types

The avatar component can be configured to display in various shape types, including circular or square, to best represent different types of entities.

Use a circle for people and a square for product or business-related images. Circles emphasize individuality and work best for people, while squares convey structure and are better suited for products, companies, or other business objects. This distinction helps users quickly recognize whether content represents a person or a business.

In general, the avatar component is typically used in a circular or square shape. Custom shapes can be defined using CSS classes.

Avatar shapes

Size types

Predefined sizes

The avatar component is available in a set of predefined sizes to ensure a consistent appearance across the user interface.

Predefined sizes: XS, S, M, L, XL

The table below outlines when to use each avatar size.

Custom sizes

If your use case requires it, you can also set a custom size.

When using a custom avatar size with initials or icons:

• Ensure that the font size is consistent with the size of the component itself.
• If your custom size is between two predefined sizes, use the font size corresponding to the smaller predefined size.

Example: If your avatar is 5.5 rem (between sizes L and XL), use the font size for size L (2 rem).

Scale types

You can specify how the original image fits into the avatar:

• Cover (default) – The size of the image is scaled up to completely cover the avatar area. As a result, parts of the image may be outside the avatar shape. Use the “cover” fit type if the focal point is in the center of the image.
• Contain – The image is scaled down to fit into the component area. The entire image is displayed, but it might not completely fill the shape. In this case, the avatar displays a default background color. The image itself is always centered inside the shape. Use the “contain” fit type for images that need to be displayed in full.

Avatar scale types: cover scale type (A) and contain scale type (B)

States

Component states

The avatar component supports three component states: enabled, disabled, and hidden.

Avatar component states: enabled (A) and disabled (B)

For more information, see Component States.

Interaction states

The avatar component supports four interaction states: regular, hover, down, and down-hover.

A: Regular
B: Hover
C: Down: This state is sometimes described as an “active” or “active/toggled” state.
D: Down-Hover: A combination of the down and hover states.

Avatar interaction states

For more information, see Interaction States.

:badge, info, large, _, SAPUI5 only:

The SAPUI5 avatar component also supports an active/toggled state, which inherits the styling of the standard button. The active/toggled state changes the visual appearance of the avatar even if the focus is changed to another component.

Avatar active/toggled state

Value states

Badges on avatars can display value states to indicate status. Each state uses a distinct color and icon to help users quickly understand the context:

A: Negative: Indicates an error or issue that requires attention or resolution.
B: Critical: Signals a warning or something that needs caution or a follow-up action.
C: Positive: Shows success or confirmation that an action has been completed.
D: Information: Provides neutral information or context without implying an issue.
E: None: No value state is shown. When the avatar has no image, the badge can display a camera icon to prompt the user to change a picture.

Badge value states

For more information, see Value States.

Behavior and Interaction

Focus

After a user clicks an interactive avatar, it receives focus. The pressed state is active while the mouse button is down.

Avatar mouse interaction – hover, press or click

Fallback icon

You can set a fallback icon to appear when the avatar can’t display its intended content. This icon shows up automatically in cases where the image source is incorrect or unavailable, or when the avatar is too small to display the initials properly.

Fallback icon with product icon (A), person icon (B), and custom fallback icon (C)

Tooltip :badge, info, large, _, SAPUI5 only:

When adding a badge to the avatar component, always pair it with a tooltip that explains the action. This ensures users understand its purpose and avoids any confusion.

The badge’s tooltip is displayed when the user hovers the mouse pointer over the badge.

When using interactive avatars, always include both a tooltip and an alternative text to support screen reader users.

Interactive avatar with a tooltip

Responsiveness

The avatar adapts to different layouts using five predefined sizes optimized for each device type.

Use the predefined sizes to match the surrounding layout density – from compact table items to spacious app headers – ensuring a consistent visual rhythm across your application.

For a full overview of available sizes and their recommended use cases, see Size Types.

Accessibility

SAP follows international standards, such as WCAG and WAI-ARIA, and strives to make our business solutions accessible and inclusive.

For more information, see Accessibility in SAP Fiori and the Accessibility Design Tools Handbook.

Keyboard navigation

The following keyboard combinations are supported by the SAPUI5 Avatar component.

Screen reader support

Provide concise alt text that describes what the avatar represents.

Add clear alternative text to every avatar image so it’s announced by screen readers and shown when the image isn’t available or can’t be displayed.

When the avatar is just used for decorative purpose (e.g avatar username is displayed in text beside the avatar), the aria role for the avatar should be ‘presentation’ so that it’s ignored by accessibility tools to avoid repetitive information for screen reader user.

For an interactive avatar or badge, provide a tooltip and an alternative text to indicate the available action.

For details on screen reader support and Accessible Rich Internet Applications (ARIA), see UI5 Screen Reader Support and WAI-ARIA Authoring.

Content

Localization

Initials

Some languages don’t build on an alphabet, or don’t use initials at all. In such cases, the gender-neutral person icon is displayed instead.

Reading direction

For right-to-left languages, such as Arabic or Hebrew, the position of the avatar badge is mirrored. This way, badge placement aligns naturally with the reading direction.

Framework Comparison

Some behaviors differ between frameworks due to implementation specifics. The table below summarizes the differences between SAPUI5 and SAP Web Components and lists the framework-specific patterns.

[internal_only] To request one of these features for SAP Web Components, submit an InnerSource request. [/internal_only]

Related Links