OAvatar

OAvatar displays a user profile image with fallback initials or icon and optional presence status.

Usage

Step by step

1. Import OAvatar from the ooko-ui/avatar public subpath.
2. Provide a src URL for the user's image, or a name to generate initials.
3. Optionally add a status to show an online/offline indicator.
4. Adjust size, shape, color, and statusPosition to match your design.

Example

The rendered example and its source come from the same Vue single-file component.

AL

Interactive playground

Change the image, name, size, shape, color, status, and status position. The preview updates immediately.

AL

Name Color primarysecondaryinfosuccesswarningdangerneutral Size xssmmdlgxl Shape circlesquare Status onlineofflinebusyaway Status position bottom-righttop-rightbottom-lefttop-left

Props

Prop	Type	Default	Description
src	string	undefined	Source URL of the avatar image.
alt	string	undefined	Accessible description of the avatar image. Required when src is provided.
name	string	undefined	User name used to generate initials when no image is available.
size	OAvatarSize	"md"	Visual size of the avatar.
shape	OAvatarShape	"circle"	Shape of the avatar container.
color	"primary" | "secondary" | "info" | "success" | "warning" | "danger" | "neutral"	"primary"	Color applied to the fallback background when no image is displayed.
status	OAvatarStatus	undefined	Status indicator displayed as an overlay badge.
statusPosition	OAvatarStatusPosition	"bottom-right"	Position of the status badge relative to the avatar.
icon	Component	undefined	Vue component rendered as the fallback icon when no image or name is provided.

Events

Event	Payload	Description
error	Event	Fired when the avatar image fails to load.

Slots

Slot	Props	Description
default	none	Provides custom fallback content (e.g., initials or icon) when no image is displayed.

Related types

Type	Definition
OAvatarShape	type OAvatarShape = "circle" | "square";
OAvatarSize	type OAvatarSize = "xs" | OokoFormControlSize | "lg" | "xl";
OAvatarStatus	type OAvatarStatus = "online" | "offline" | "busy" | "away";
OAvatarStatusPosition	type OAvatarStatusPosition = "bottom-right" | "top-right" | "bottom-left" | "top-left";
OokoFormControlSize	type OokoFormControlSize = "sm" | "md";
OokoColor	type OokoColor = (typeof OOKO_COLORS)[number];

CSS custom properties

Custom property	Default	Description
--o-avatar-border-radius-circle	var(--o-radius-round)	Sets the avatar corner radius for circle shape.
--o-avatar-border-radius-square	var(--o-radius-control)	Sets the avatar corner radius for square shape.
--o-avatar-fallback-border-width	0	Sets the avatar border width when no image is loaded.
--o-avatar-fallback-color	var(--o-text-color-inverted)	Sets the avatar fallback icon color.
--o-status-border-color	var(--o-background-color-default)	Sets the status dot border color (uses background for contrast).

Override example

:root {
  --o-avatar-border-radius-square: var(--o-radius-round);
  --o-avatar-fallback-border-width: 2px;
}

Accessibility

• The avatar content has role="img" and an accessible name derived from alt, name, or a generic "User avatar" label.
• When an image is provided, alt is required for a meaningful description; if omitted, the component uses name or the fallback label.
• Decorative icons and initials are included in the avatar image semantics rather than announced separately.
• The status badge is a separate, non-interactive image with an accessible label describing the status.
• Native attributes are forwarded to the root span.

Behavior and edge cases

• If src fails to load, the component automatically falls back to initials (from name) or the default/icon slot.
• The name prop generates two-letter uppercase initials from the first two words.
• The icon prop accepts any Vue icon component; the default slot overrides both icon and generated initials.
• status renders a colored dot badge; statusPosition controls its corner placement.
• Sizes: xs (24 px), sm (32 px), md (40 px), lg (48 px), xl (64 px) at the default root scale.
• App defaults may configure color, shape, size, and statusPosition; direct props take precedence.
• SSR-safe: image loading state and fallbacks render deterministically on the server.