Avatar

shadow

wje-avatar is designed for fast visual identification of a person, team, brand, or other entity. It can render an image or other slotted content, fallback initials derived from label, and supporting icon, status, or secondary content.

Basic usage

This example places the three most important modes next to each other: an avatar with an image, initials, and an icon. It quickly shows that wje-avatar is not limited to profile pictures.

Avatar size

This example demonstrates that the size attribute changes the dimensions of the outer avatar shell. The same image or slotted content can therefore scale without changing the inner markup.

Avatar size with initials

The same size variants also work in initials mode. When the boolean initials attribute is present, the component prefers generated initials over the default slotted content.

Avatar with icon

If you want the avatar to act more like a compact status or action marker than a profile image, place an icon into the icon slot.

Avatar with initials

This is the most common fallback scenario. The component takes text from label, derives initials, and automatically computes contrasting background and text colors.

Avatar with status

In this example, wje-status is placed into the status slot so it appears on one of the four avatar corners according to status-placement. This works well for online state, verification, or similar compact indicators.

Avatar as a dropdown trigger

There is an important composition detail here: wje-avatar is placed into the trigger slot of wje-dropdown. The placement, trigger, and offset attributes therefore belong to the dropdown, not the avatar.

Avatar with tooltip

This example is also based on composition with another component. The tooltip is not built into the avatar; you get it by using the avatar as the wje-tooltip target content.

Group of avatars

This example shows the boundary between what the component does and what surrounding layout CSS does. wje-avatar does not provide a built-in group wrapper or group API; overlapping avatars are achieved through an external container and custom CSS.

CSS custom properties

When you need to change dimensions, typography, or colors without rewriting the markup, use the component CSS variables.

Things To Keep In Mind

• label together with initials is the most practical non-image fallback.
• status-placement controls where the status slot is rendered on the avatar edge.
• The default slot holds the main content, while icon, status, and secondary cover supporting use cases.
• The helper method isImage() checks whether the avatar currently contains wje-img.
• Click, hover, or menu-open behavior is usually owned by a parent component such as wje-dropdown or wje-tooltip.

Accessibility

• If you render an image, provide meaningful alternative text on the slotted img or wje-img.
• If you render initials, set label; the component also uses it for the host aria-label.
• When the avatar is used as a dropdown or tooltip trigger, accessibility is largely handled by the parent component because the interaction lives there.

Best Practices

• For non-image fallback, use label together with initials.
• If the avatar triggers an action or a menu, do not leave users without nearby textual context.
• For grouped avatars, handle overlap and ring styling through external CSS rather than expecting a built-in group API.
• Use the secondary slot only when its position and meaning are clear in your layout; the component does not provide elaborate layout logic for it.

Attributes and Properties

initials

Description	Renders generated initials from label instead of the default slotted content.
Attribute	initials
Type	boolean
Default	false

label

Description	Provides the source text for generated initials and the accessible label of the avatar.
Attribute	label
Type	string
Default	-

size

Description	Selects a predefined avatar size such as small, medium, normal, large, or larger variants.
Attribute	size
Type	string
Default	medium

statusPlacement

Description	Positions the status slot on one of the avatar corners.
Attribute	status-placement
Type	string
Default	-

Events

No events available for this component.

Methods

isImage

Description	Method to check if the avatar is an image.
Signature	() => boolean

CSS Shadow Parts

Name	Description
native	The component's native wrapper.
status	The positioned slot container for status content.
secondary	The slot container for secondary avatar content.

CSS Custom Properties

Name	Description
--wje-avatar-size	Controls the overall rendered size of the avatar shell.
--wje-avatar-font-size	Controls the font size used for initials and text content.
--wje-avatar-font-weight	Controls the font weight used for initials and text content.
--wje-avatar-color	Controls the text color inside the avatar.
--wje-avatar-background-color	Controls the background color of the avatar surface.
--wje-avatar-border-radius	Controls the avatar border radius.
--wje-avatar-border-color	Controls the avatar border color when a border is applied.
--wje-avatar-border-width	Controls the avatar border width when a border is applied.
--wje-avatar-border-style	Controls the avatar border style when a border is applied.

Slots

Name	Description
default	Slot for the main avatar content, typically an image.
icon	Slot for an icon rendered inside the avatar.
status	Slot for a status badge or indicator positioned on the avatar edge.
secondary	Slot for additional secondary content rendered with the avatar.