Use Avatar

<jangle-avatar> represents a person or object visually. It owns its image, initials, and fallback icon. Your application owns surrounding text, layout, and actions. Avatar is not a link or button.

Add an avatar

Configure package access, then load the theme and registration:

import '@jangle-ui/tokens/tokens.css';
import '@jangle-ui/components/avatar/register';

<jangle-avatar src="/people/alex.jpg" initials="AL" label="Alex Lee"></jangle-avatar>

The default is a circular 40px frame with neutral-subtle fallback colors. A loaded image takes precedence over explicit initials, then icon (default system:user). Initials or the icon remain visible while loading or after image failure, without changing the frame's size. Supply initials using your application's naming and localization rules; prefer one or two graphemes.

fit="cover" crops to fill the frame. fit="contain" preserves a complete image, useful for logos. The image CSS part supports object-position for application-specific cropping.

Choose appearance

color="neutral|brand" selects identity color, while treatment="subtle|strong" selects emphasis. Defaults are neutral and subtle. Brand follows the configured theme. Recipes affect fallback text, icons, and the background behind an image; they do not tint images. Color does not declare status or presence. Use context="inverse" on an application-owned inverse surface.

size="xs|sm|md|lg|xl" selects coordinated frame, initials, and icon recipes. Frame sizes are 24, 32, 40, 48, and 64px at the default scale. Medium is the default.

shape="circle" (the default) stays circular at every size and corner profile. Choose shape="square" for a square frame with corners that follow the theme. Override only the square variant with --jangle-avatar-radius; for example, 0px gives sharp corners. The hook has no effect on circles.

Customize identity colors

<jangle-avatar
  initials="NS"
  label="Northstar"
  shape="square"
  style="--jangle-avatar-background:#ecfeff; --jangle-avatar-color:#164e63"
></jangle-avatar>

Set --jangle-avatar-background and --jangle-avatar-color together on the host or an ancestor. Applications own contrast and appearance/context adaptation for these custom pairs.

Names and image errors

Set label when a standalone avatar needs an accessible identity name. Omit it when adjacent text or an owning control already identifies the person or object; the avatar is then decorative. Its label names whichever content is visible, without adding a tooltip or live announcement. Avatar has no focus, keyboard, or click behavior. A containing control owns its accessible name and hit target.

jangle-avatar-error bubbles and crosses shadow boundaries with detail: { src: string } when the current image fails. Fallback rendering is automatic. Listen only when your application needs to record the error or choose another image. Avatar has no content slots or public methods.

See Avatar in Storybook for examples and the complete API.

Migrate from the 0.8.0 radius API

Avatar no longer accepts radius. Replace radius="full" with shape="circle" (or omit it). Replace radius="none" with shape="square" and --jangle-avatar-radius: 0px. For an old default avatar with a custom radius, add shape="square" to preserve that customization; a default avatar without a radius override remains circular. TypeScript imports change from AvatarRadius / avatarRadii to AvatarShape / avatarShapes.