<!--
Source: https://www.theui.dev/docs/avatar
Part of the theui-svelte documentation. Index: https://www.theui.dev/llms.txt
-->

# Avatar

The Avatar component shows who someone is. It takes a photo, falls back to their initials when there is no photo, and to a person icon when there is no name either. Add a status dot for presence, or group several avatars into a stack.

## Example

Import the component and pass an image with `src` and `alt`. Without an image, pass a `name` and the avatar shows the initials.

```html
<script>
  import { Avatar } from "theui-svelte";
</script>

<Avatar src="/avatar.png" alt="Ayesha Rahman" />
<Avatar name="Jane Cooper" />
<Avatar alt="Unknown person" />
```

## Sizes

The `size` prop accepts `xs`, `sm`, `md`, `lg`, `xl` and `2xl`. The default is `md`. The text of the initials scales with the avatar.

```html
<Avatar size="xs" name="Extra Small" />
<Avatar size="sm" name="Small Size" />
<Avatar size="md" name="Medium Size" />
<Avatar size="lg" name="Large Size" />
<Avatar size="xl" name="Extra Large" />
<Avatar size="2xl" name="Double Extra" />
```

## Rounded Corner

Avatars are circles by default. The `rounded` prop takes `none`, `sm`, `md`, `lg`, `xl`, `2xl` and `full`, so a square avatar is one prop away.

```html
<Avatar rounded="full" src="/avatar.png" alt="Full" />
<Avatar rounded="2xl" src="/avatar.png" alt="2xl" />
<Avatar rounded="lg" src="/avatar.png" alt="lg" />
<Avatar rounded="md" src="/avatar.png" alt="md" />
<Avatar rounded="none" src="/avatar.png" alt="none" />
```

## Fallback

When the image fails to load, the avatar falls back on its own: first to the `name` initials, then to a person icon. You can also pass your own content as the child of the component, such as an icon or an emoji.

```html
<!-- A broken image falls back to the initials -->
<Avatar src="https://example.com/missing.png" name="Broken Image" />

<!-- No image: the initials are shown -->
<Avatar name="Rafiq Islam" rounded="lg" />

<!-- Your own content -->
<Avatar class="bg-brand-500 text-on-brand">
  <span class="text-lg">🐧</span>
</Avatar>
```

## Status

The `status` prop adds a presence dot: `online`, `offline`, `busy` or `away`. Use `statusPosition` to move it to the `top`, the default is `bottom`. The status is read out by screen readers, so the dot is never colour alone.

```html
<Avatar src="/a.png" alt="Ayesha" status="online" />
<Avatar src="/b.png" alt="Bilal" status="away" />
<Avatar src="/c.png" alt="Chandra" status="busy" />
<Avatar name="Dina Haque" status="offline" />
<Avatar size="xl" src="/e.png" alt="Elias" status="online" statusPosition="top" />
```

## Link Avatar

Give the component an `href` and the whole avatar becomes a link. Any other attribute, such as `target` or `title`, is passed to the element as well.

```html
<Avatar href="/profile/ayesha" src="/avatar.png" alt="Ayesha Rahman, view profile" />
<Avatar href="/profile/jane" name="Jane Cooper" />
```

## Avatar Group

Wrap avatars in an `AvatarGroup` to stack them. The group sets `size` and `rounded` for every avatar inside, so you set them once.

```html
<script>
  import { Avatar, AvatarGroup } from "theui-svelte";
</script>

<AvatarGroup ariaLabel="Project members">
  <Avatar src="/a.png" alt="Ayesha" />
  <Avatar src="/b.png" alt="Bilal" />
  <Avatar name="Chandra Das" />
</AvatarGroup>
```

## Group Limit

Set `max` to show only the first few avatars. The rest are counted in a final avatar, such as **+3**, which screen readers announce as "3 more".

```html
<AvatarGroup max={3} ariaLabel="Team">
  <Avatar src="/a.png" alt="Ayesha" />
  <Avatar src="/b.png" alt="Bilal" />
  <Avatar src="/c.png" alt="Chandra" />
  <Avatar src="/d.png" alt="Dina" />
  <Avatar src="/e.png" alt="Elias" />
</AvatarGroup>

<AvatarGroup max={2} size="lg" rounded="lg" ariaLabel="Editors">
  ...
</AvatarGroup>
```

## Customization

Pass your own classes with `class` to change the colour of the fallback, and use `imgClasses` and `statusClasses` for the image and the status dot. On a group, `moreClasses` styles the "+N" avatar.

```html
<Avatar name="Brand Colour" class="bg-brand-500 text-on-brand" />
<Avatar name="Soft Look" class="bg-info-100 text-info-900" />
<Avatar src="/r.png" alt="Ring" class="ring-2 ring-brand-500 ring-offset-2" />
<Avatar src="/s.png" alt="Big status" status="online" statusClasses="size-1/3 bg-success-400" />

<AvatarGroup max={1} moreClasses="bg-brand-500 text-on-brand">
  ...
</AvatarGroup>
```

## Accessibility

An avatar with an image needs an `alt`. Use the person's name, or an empty string when the avatar sits next to their name already, so it is not read twice. An avatar showing initials or an icon is marked as an image and named by `alt` or `name`, so a screen reader says the full name instead of the two letters. The status dot carries its own text, such as "Online", and the overflow avatar of a group announces how many people are left. Give the group itself an `ariaLabel` that says what the people have in common.

## Configuration

### Avatar

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | string | `undefined` | Image of the avatar. When it is missing or fails to load, the initials or the icon are shown instead. |
| `alt` | string | `undefined` | Alternative text of the image, and the accessible name of a fallback avatar. Use an empty string when the name is already written next to the avatar. |
| `name` | string | `undefined` | Full name of the person. Its initials are shown when there is no image, and screen readers read the full name. |
| `size` | [AVATAR_SIZE](https://www.theui.dev/docs/types#avatar-size-type) | `md` | Size of the avatar: "xs", "sm", "md", "lg", "xl" or "2xl". Inside an AvatarGroup the group decides. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Defines the border radius of the component. Inside an AvatarGroup the group decides. |
| `status` | [AVATAR_STATUS](https://www.theui.dev/docs/types#avatar-status-type) | `undefined` | Shows a presence dot: "online", "offline", "busy" or "away". |
| `statusPosition` | "top" \| "bottom" | `bottom` | Corner the status dot sits in. |
| `href` | string | `undefined` | Turns the whole avatar into a link. |
| `imgClasses` | string | `` | Custom classes for the image. |
| `statusClasses` | string | `` | Custom classes for the status dot. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the avatar itself, merged with the default classes. Use it to change the fallback colours. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | Custom content of the avatar, such as an icon. Used when there is no image. |

### AvatarGroup

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | number | `undefined` | Number of avatars to show. The rest are counted in a final "+N" avatar. |
| `size` | [AVATAR_SIZE](https://www.theui.dev/docs/types#avatar-size-type) | `md` | Size of every avatar in the group. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Border radius of every avatar in the group. |
| `ariaLabel` | string | `undefined` | Accessible name of the group, such as "Project members". |
| `moreClasses` | string | `` | Custom classes for the "+N" avatar. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the group element, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The Avatar components of the group. |

---

Category: Components
Keywords: avatar, user, profile, status, component, svelte, svelte-5, theui-svelte, component-library, ui, tailwindcss
Full documentation set: https://www.theui.dev/llms-full.txt
