# Avatar

Image avatar with fallback. 4 sizes (sm/md/lg/xl), circle or square shape.

- Package: `@mielui/svelte`
- Component version: `1.0.0`
- Depends on Mielui components: _internal/utils
- Shared utilities: utils.createContext, utils.cn

## Install

~~~~sh
pnpm dlx @mielui/svelte add avatar
~~~~

## API

This reference is generated at build time from the component manifest, public `index.ts`, and documentation examples below. Changes to those source files are reflected here in the published Markdown. Standard Svelte and HTML attributes accepted by the exported prop types are supported.


### Fallback

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| class | string \| undefined | - | No | No | Classes added to the element. |



### Image

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| src | string \| undefined | - | No | No | Image address. |
| alt | string \| undefined | '' | No | No | Image description. Leave it empty when the name is shown beside the avatar. |
| class | (string & (ClassValue \| null)) \| undefined | - | No | No | Classes added to the element. |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |

Also accepts the native HTML attributes and events listed in the rendered API reference.

### Root

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" \| undefined | 'md' | No | No | Diameter of the avatar. |
| shape | "circle" \| "square" \| undefined | 'circle' | No | No | Outline of the avatar. |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |
| class | string \| undefined | - | No | No | Classes added to the element. |



### Public types

~~~~ts
import type { DefaultProps } from '@mielui/svelte/utils';
import type { Snippet } from 'svelte';
import type { HTMLImgAttributes } from 'svelte/elements';
import Root from './avatar.svelte';
import Fallback from './avatar-fallback.svelte';
import Image from './avatar-image.svelte';

export type AvatarProps = {
    /** Diameter of the avatar. */
    size?: 'sm' | 'md' | 'lg' | 'xl';
    /** Outline of the avatar. */
    shape?: 'circle' | 'square';
    /** Content rendered inside. */
    children?: Snippet;
} & DefaultProps;

export type AvatarImageProps = {
    /** Image address. */
    src?: string;
    /** Image description. Leave it empty when the name is shown beside the avatar. */
    alt?: string;
} & DefaultProps &
    HTMLImgAttributes;

export type AvatarFallbackProps = {
    /** Content rendered inside. */
    children?: Snippet;
} & DefaultProps;

export { Fallback, Image, Root };
~~~~

## Examples

### Hero

~~~~svelte
<script lang="ts">
    import * as Avatar from '@mielui/svelte/components/avatar';

    const team = [
        {
            name: 'Maya Chen',
            initials: 'MC',
            role: 'Design lead'
        },
        {
            name: 'Theo Martin',
            initials: 'TM',
            role: 'Engineer'
        },
        {
            name: 'Amira Diallo',
            initials: 'AD',
            role: 'Product manager'
        }
    ];
</script>

<div class="flex w-full max-w-xs flex-col gap-5">
    <div class="flex items-center gap-3">
        <Avatar.Root size="lg">
            <Avatar.Image src="https://github.com/mielsense.png" alt="" />
            <Avatar.Fallback>MI</Avatar.Fallback>
        </Avatar.Root>
        <div class="flex min-w-0 flex-col">
            <span class="truncate text-sm font-medium text-foreground">Mielsense</span>
            <span class="truncate text-sm text-foreground-muted">Maintainer</span>
        </div>
    </div>
    <ul class="m-0 flex list-none flex-col gap-3 p-0">
        {#each team as member (member.name)}
            <li class="flex items-center gap-3">
                <Avatar.Root size="sm">
                    <Avatar.Fallback>{member.initials}</Avatar.Fallback>
                </Avatar.Root>
                <span class="min-w-0 flex-1 truncate text-sm text-foreground">{member.name}</span>
                <span class="shrink-0 text-sm text-foreground-muted">{member.role}</span>
            </li>
        {/each}
    </ul>
</div>
~~~~

### Shapes

~~~~svelte
<script lang="ts">
    import * as Avatar from '@mielui/svelte/components/avatar';
</script>

<div class="flex items-center justify-center gap-4">
    <Avatar.Root shape="circle"><Avatar.Fallback>CR</Avatar.Fallback></Avatar.Root>
    <Avatar.Root shape="square"><Avatar.Fallback>SQ</Avatar.Fallback></Avatar.Root>
</div>
~~~~

### Sizes

~~~~svelte
<script lang="ts">
    import * as Avatar from '@mielui/svelte/components/avatar';
</script>

<div class="flex items-center justify-center gap-4">
    <Avatar.Root size="sm"><Avatar.Fallback>SM</Avatar.Fallback></Avatar.Root>
    <Avatar.Root size="md"><Avatar.Fallback>MD</Avatar.Fallback></Avatar.Root>
    <Avatar.Root size="lg"><Avatar.Fallback>LG</Avatar.Fallback></Avatar.Root>
    <Avatar.Root size="xl"><Avatar.Fallback>XL</Avatar.Fallback></Avatar.Root>
</div>
~~~~

### With Image

~~~~svelte
<script lang="ts">
    import * as Avatar from '@mielui/svelte/components/avatar';
</script>

<div class="flex items-center justify-center">
    <Avatar.Root>
        <Avatar.Image src="data:image/png;base64," alt="Alex Morgan" />
        <Avatar.Fallback>AM</Avatar.Fallback>
    </Avatar.Root>
</div>
~~~~

For the rendered reference, visit [/docs/components/avatar](/docs/components/avatar).