Data Display

Avatar

Display user profile images with automatic initials fallback. Supports 9 sizes, border radius variants, chip indicators, icon fallback, and style overrides.

Playground

Experiment with different props in real-time.

Size

Rounded

Src

Chip

Basic Usage

Pass a src and alt to display a user avatar.

<script lang="ts">
  import { Avatar } from 'sv5ui';
</script>

<Avatar src="https://i.pravatar.cc/300?u=1" alt="John Doe" />

Sizes

9 sizes from 3xs (16px) to 3xl (48px).

<Avatar size="3xs" src="https://i.pravatar.cc/300?u=1" alt="User" />
<Avatar size="2xs" src="https://i.pravatar.cc/300?u=2" alt="User" />
<Avatar size="xs" src="https://i.pravatar.cc/300?u=3" alt="User" />
<Avatar size="sm" src="https://i.pravatar.cc/300?u=4" alt="User" />
<Avatar size="md" src="https://i.pravatar.cc/300?u=5" alt="User" />
<Avatar size="lg" src="https://i.pravatar.cc/300?u=6" alt="User" />
<Avatar size="xl" src="https://i.pravatar.cc/300?u=7" alt="User" />
<Avatar size="2xl" src="https://i.pravatar.cc/300?u=8" alt="User" />
<Avatar size="3xl" src="https://i.pravatar.cc/300?u=9" alt="User" />

Rounded

Control border radius with the rounded prop.

full

none

<Avatar rounded="full" src="https://i.pravatar.cc/300?u=1" alt="User" />
<Avatar rounded="lg" src="https://i.pravatar.cc/300?u=2" alt="User" />
<Avatar rounded="md" src="https://i.pravatar.cc/300?u=3" alt="User" />
<Avatar rounded="sm" src="https://i.pravatar.cc/300?u=4" alt="User" />
<Avatar rounded="none" src="https://i.pravatar.cc/300?u=5" alt="User" />

With Initials

When no src is provided, initials are automatically generated from the alt prop.

<!-- Auto-generated from alt prop -->
<Avatar alt="John Doe" />
<Avatar alt="Alice Smith" />
<Avatar alt="Bob" />

Custom Fallback Text

Use the text prop to display custom fallback text instead of auto-generated initials.

<!-- Custom text overrides auto-generated initials -->
<Avatar text="AB" />
<Avatar text="OK" />
<Avatar text="?" />

Icon Fallback

Use the icon prop for an Iconify icon fallback.

<Avatar icon="lucide:user" />
<Avatar icon="lucide:building" size="lg" />
<Avatar icon="lucide:bot" size="xl" />

Chip Indicator

Add a status chip with chip. Pass true for default or an object to customize.

<!-- Simple chip (default green) -->
<Avatar src="https://i.pravatar.cc/300?u=1" alt="User" chip />

<!-- Custom chip color -->
<Avatar src="https://i.pravatar.cc/300?u=2" alt="User" chip={{ color: 'error' }} />
<Avatar src="https://i.pravatar.cc/300?u=3" alt="User" chip={{ color: 'warning' }} />
<Avatar src="https://i.pravatar.cc/300?u=4" alt="User" chip={{ color: 'info' }} />

Styled Examples

Customize appearance with the ui prop.

<Avatar
  src="https://i.pravatar.cc/300?u=11"
  alt="Styled"
  ui={{
    root: 'ring-2 ring-primary ring-offset-2 ring-offset-surface',
  }}
/>
<Avatar
  alt="Custom Fallback"
  ui={{
    fallback: 'bg-primary text-on-primary',
  }}
/>

Custom Children

Use the children snippet to render fully custom content inside the avatar.

<Avatar size="lg">
  <Icon name="lucide:user" class="size-5" />
</Avatar>

<Avatar size="lg" ui={{ root: 'bg-primary text-on-primary' }}>
  <Icon name="lucide:star" class="size-5" />
</Avatar>

<Avatar size="lg" ui={{ root: 'bg-success text-on-success' }}>
  <Icon name="lucide:check" class="size-5" />
</Avatar>

UI Slots

Use the ui prop to override classes on internal elements.

Slot	Description
`root`	`Root avatar container — controls size and shape`
`image`	`Image element — controls object-fit and rendering`
`fallback`	`Fallback element — shown when image is unavailable`
`icon`	`Icon element for icon fallback`

Snippets

Snippet	Description
`children`	`Custom content inside the avatar — overrides image, text, and icon`
`fallback`	`Custom fallback content rendered when image is unavailable`

Props

Prop	Type	Default	Description
`size`	`'3xs' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`	`'md'`	`Controls dimensions of the avatar`
`src`	`string`	`-`	`URL of the image to display`
`alt`	`string`	`-`	`Alt text; also used to auto-generate initials`
`text`	`string`	`-`	`Custom fallback text (overrides auto initials)`
`icon`	`string`	`-`	`Iconify icon name for fallback`
`rounded`	`'full' \| 'lg' \| 'md' \| 'sm' \| 'none'`	`'full'`	`Border radius style`
`chip`	`boolean \| AvatarChipProps`	`-`	`Status chip indicator`
`loading`	`'lazy' \| 'eager'`	`'eager'`	`Image loading strategy`
`delayMs`	`number`	`0`	`Delay before showing the avatar`
`ref`	`HTMLDivElement`	`-`	`Bindable reference to root element`
`class`	`string`	`-`	`Additional CSS classes on root element`
`ui`	`Record<Slot, Class>`	`-`	`Override slot classes`

Accordion AvatarGroup