Avatar

An enhanced avatar component for displaying user profile images with support for fallbacks, variants, colors, shapes, and grouping

Sizes

Default

2XL

Code Svelte

1
2<script lang="ts">
3	import { Avatar} from "@kareyes/aether";
4
5	const users = [
6		{ name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7		{ name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8		{ name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9		{ name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10		{ name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11	];
12</script>
13
14
15<div class="flex items-end gap-4">
16    <div class="text-center">
17        <Avatar size="xs" src={users[0].image} alt="Extra Small" fallback="XS" />
18        <p class="text-xs mt-2">XS</p>
19    </div>
20    <div class="text-center">
21        <Avatar size="sm" src={users[0].image} alt="Small" fallback="SM" />
22        <p class="text-xs mt-2">SM</p>
23    </div>
24    <div class="text-center">
25        <Avatar size="default" src={users[0].image} alt="Default" fallback="MD" />
26        <p class="text-xs mt-2">Default</p>
27    </div>
28    <div class="text-center">
29        <Avatar size="lg" src={users[0].image} alt="Large" fallback="LG" />
30        <p class="text-xs mt-2">LG</p>
31    </div>
32    <div class="text-center">
33        <Avatar size="xl" src={users[0].image} alt="Extra Large" fallback="XL" />
34        <p class="text-xs mt-2">XL</p>
35    </div>
36    <div class="text-center">
37        <Avatar size="2xl" src={users[0].image} alt="2XL" fallback="2XL" />
38        <p class="text-xs mt-2">2XL</p>
39    </div>
40</div>
41

Shapes

Circle

Rounded

Square

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6        { name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7        { name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8        { name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9    ];
10</script>
11
12<div class="flex items-center gap-6">
13    <div class="text-center">
14        <Avatar shape="circle" src={users[0].image} alt="Circle" fallback="CI" size="lg" />
15        <p class="text-sm mt-2">Circle</p>
16    </div>
17    <div class="text-center">
18        <Avatar shape="rounded" src={users[0].image} alt="Rounded" fallback="RO" size="lg" />
19        <p class="text-sm mt-2">Rounded</p>
20    </div>
21    <div class="text-center">
22        <Avatar shape="square" src={users[0].image} alt="Square" fallback="SQ" size="lg" />
23        <p class="text-sm mt-2">Square</p>
24    </div>
25</div>

Variants

Default

Bordered

Solid

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6        { name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7        { name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8        { name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9    ];
10</script>
11
12<div class="flex items-center gap-6">
13    <div class="text-center">
14        <Avatar variant="default" src={users[0].image} alt="Default" fallback="DF" size="lg" />
15        <p class="text-sm mt-2">Default</p>
16    </div>
17    <div class="text-center">
18        <Avatar variant="bordered" src={users[0].image} alt="Bordered" fallback="BO" size="lg" />
19        <p class="text-sm mt-2">Bordered</p>
20    </div>
21    <div class="text-center">
22        <Avatar variant="solid" color="primary" fallback="SO" size="lg" />
23        <p class="text-sm mt-2">Solid</p>
24    </div>
25</div>
26

Colors

Default

Primary

Secondary

Green

Yellow

Red

Blue

Purple

Pink

Gradient

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6        { name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7        { name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8        { name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9    ];
10</script>
11<div class="flex flex-wrap gap-4">
12    <div class="text-center">
13        <Avatar color="default" fallback="DF" />
14        <p class="text-xs mt-2">Default</p>
15    </div>
16    <div class="text-center">
17        <Avatar color="primary" fallback="PR" />
18        <p class="text-xs mt-2">Primary</p>
19    </div>
20    <div class="text-center">
21        <Avatar color="secondary" fallback="SE" />
22        <p class="text-xs mt-2">Secondary</p>
23    </div>
24    <div class="text-center">
25        <Avatar color="green" fallback="SU" />
26        <p class="text-xs mt-2">Green</p>
27    </div>
28    <div class="text-center">
29        <Avatar color="yellow" fallback="WA" />
30        <p class="text-xs mt-2">Yellow</p>
31    </div>
32    <div class="text-center">
33        <Avatar color="red" fallback="DA" />
34        <p class="text-xs mt-2">Red</p>
35    </div>
36    <div class="text-center">
37        <Avatar color="blue" fallback="IN" />
38        <p class="text-xs mt-2">Blue</p>
39    </div>
40    <div class="text-center">
41        <Avatar color="purple" fallback="PU" />
42        <p class="text-xs mt-2">Purple</p>
43    </div>
44    <div class="text-center">
45        <Avatar color="pink" fallback="PI" />
46        <p class="text-xs mt-2">Pink</p>
47    </div>
48    <div class="text-center">
49        <Avatar color="gradient" fallback="GR" />
50        <p class="text-xs mt-2">Gradient</p>
51    </div>
52</div>
53

Bordered with Colors

Bordered variant combined with different color options creates a colored ring around the avatar.

Default

Primary

Secondary

Green

Yellow

Red

Blue

Purple

Pink

Gradient

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6        { name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7        { name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8        { name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9    ];
10
11<div class="flex flex-wrap gap-4">
12    <div class="text-center">
13        <Avatar variant="bordered" color="default" fallback="DF" size="lg" />
14        <p class="text-xs mt-2">Default</p>
15    </div>
16    <div class="text-center">
17        <Avatar variant="bordered" color="primary" fallback="PR" size="lg" />
18        <p class="text-xs mt-2">Primary</p>
19    </div>
20    <div class="text-center">
21        <Avatar variant="bordered" color="secondary" fallback="SE" size="lg" />
22        <p class="text-xs mt-2">Secondary</p>
23    </div>
24    <div class="text-center">
25        <Avatar variant="bordered" color="green" fallback="SU" size="lg" />
26        <p class="text-xs mt-2">Green</p>
27    </div>
28    <div class="text-center">
29        <Avatar variant="bordered" color="yellow" fallback="WA" size="lg" />
30        <p class="text-xs mt-2">Yellow</p>
31    </div>
32    <div class="text-center">
33        <Avatar variant="bordered" color="red" fallback="DA" size="lg" />
34        <p class="text-xs mt-2">Red</p>
35    </div>
36    <div class="text-center">
37        <Avatar variant="bordered" color="blue" fallback="IN" size="lg" />
38        <p class="text-xs mt-2">Blue</p>
39    </div>
40    <div class="text-center">
41        <Avatar variant="bordered" color="purple" fallback="PU" size="lg" />
42        <p class="text-xs mt-2">Purple</p>
43    </div>
44    <div class="text-center">
45        <Avatar variant="bordered" color="pink" fallback="PI" size="lg" />
46        <p class="text-xs mt-2">Pink</p>
47    </div>
48    <div class="text-center">
49        <Avatar variant="bordered" color="gradient" fallback="GR" size="lg" />
50        <p class="text-xs mt-2">Gradient</p>
51    </div>
52</div>

Bordered with Images

Bordered avatars work great with images too, showing a subtle colored ring.

Default

Primary

Success

Danger

Purple

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5	const users = [
6		{ name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7		{ name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8		{ name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9		{ name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10		{ name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11	];
12</script>
13
14    <div class="flex flex-wrap gap-4">
15        <div class="text-center">
16            <Avatar variant="bordered" color="default" src={users[0].image} alt="User" fallback="U1" size="lg" />
17            <p class="text-xs mt-2">Default</p>
18        </div>
19        <div class="text-center">
20            <Avatar variant="bordered" color="primary" src={users[1].image} alt="User" fallback="U2" size="lg" />
21            <p class="text-xs mt-2">Primary</p>
22        </div>
23        <div class="text-center">
24            <Avatar variant="bordered" color="green" src={users[2].image} alt="User" fallback="U3" size="lg" />
25            <p class="text-xs mt-2">Success</p>
26        </div>
27        <div class="text-center">
28            <Avatar variant="bordered" color="red" src={users[3].image} alt="User" fallback="U4" size="lg" />
29            <p class="text-xs mt-2">Danger</p>
30        </div>
31        <div class="text-center">
32            <Avatar variant="bordered" color="purple" src={users[4].image} alt="User" fallback="U5" size="lg" />
33            <p class="text-xs mt-2">Purple</p>
34        </div>
35    </div>

Bordered Shapes with Colors

Circle + Primary

Rounded + Green

Square + Purple

Square + Gradient

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4</script>
5
6<div class="flex flex-wrap gap-6">
7    <div class="text-center">
8        <Avatar 
9            variant="bordered" 
10            shape="circle" 
11            color="primary" 
12            fallback="CI" 
13            size="xl" 
14        />
15        <p class="text-sm mt-2">Circle + Primary</p>
16    </div>
17    <div class="text-center">
18        <Avatar 
19            variant="bordered" 
20            shape="rounded" 
21            color="green" 
22            fallback="RO" 
23            size="xl" 
24        />
25        <p class="text-sm mt-2">Rounded + Green</p>
26    </div>
27    <div class="text-center">
28        <Avatar 
29            variant="bordered" 
30            shape="square" 
31            color="purple" 
32            fallback="SQ" 
33            size="xl" 
34        />
35        <p class="text-sm mt-2">Square + Purple</p>
36    </div>
37    <div class="text-center">
38        <Avatar 
39            variant="bordered" 
40            shape="square" 
41            color="gradient" 
42            fallback="GR" 
43            size="xl" 
44        />
45        <p class="text-sm mt-2">Square + Gradient</p>
46    </div>
47</div>

Fallback Examples

Initials from Name

Custom Initials

Default Icon

Custom Icon

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4</script>
5
6<div class="flex items-center gap-6">
7    <div class="text-center">
8        <Avatar fallback="John Doe" color="primary" size="lg" />
9        <p class="text-sm mt-2">Initials from Name</p>
10    </div>
11    <div class="text-center">
12        <Avatar fallback="AB" color="green" size="lg" />
13        <p class="text-sm mt-2">Custom Initials</p>
14    </div>
15    <div class="text-center">
16        <Avatar size="lg" />
17        <p class="text-sm mt-2">Default Icon</p>
18    </div>
19    <div class="text-center">
20        <Avatar size="lg" color="purple">
21            {#snippet customFallback()}
22                <svg class="size-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
23                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5.121 17.804A13.937 13.937 0 0112 16c2.5 0 4.847.655 6.879 1.804M15 10a3 3 0 11-6 0 3 3 0 016 0zm6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
24                </svg>
25            {/snippet}
26        </Avatar>
27        <p class="text-sm mt-2">Custom Icon</p>
28    </div>
29</div>

Status Indicators

Display online, offline, away, and busy status with colored indicators.

Online

Offline

Away

Busy

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5	const users = [
6		{ name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7		{ name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8		{ name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9		{ name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10		{ name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11	];
12</script>
13<div class="flex flex-wrap gap-6">
14    <div class="text-center">
15        <Avatar 
16            status="online" 
17            src={users[0].image} 
18            alt="User" 
19            fallback="ON" 
20            size="xl" 
21        />
22        <p class="text-sm mt-2">Online</p>
23    </div>
24    <div class="text-center">
25        <Avatar 
26            status="offline" 
27            src={users[1].image} 
28            alt="User" 
29            fallback="OF" 
30            size="xl" 
31        />
32        <p class="text-sm mt-2">Offline</p>
33    </div>
34    <div class="text-center">
35        <Avatar 
36            status="away" 
37            src={users[2].image} 
38            alt="User" 
39            fallback="AW" 
40            size="xl" 
41        />
42        <p class="text-sm mt-2">Away</p>
43    </div>
44    <div class="text-center">
45        <Avatar 
46            status="busy" 
47            src={users[3].image} 
48            alt="User" 
49            fallback="BS" 
50            size="xl" 
51        />
52        <p class="text-sm mt-2">Busy</p>
53    </div>
54</div>
55

Notification Badges

Show notification badges with optional counts. Displays "99+" for counts over 99.

No Count

Count: 3

Count: 25

99+

Count: 99+

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6		{ name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7		{ name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8		{ name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9		{ name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10		{ name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11	];
12</script>
13
14			<div class="flex flex-wrap gap-6">
15				<div class="text-center">
16					<Avatar 
17						showNotification 
18						src={users[0].image} 
19						alt="User" 
20						fallback="NT" 
21						size="xl" 
22					/>
23					<p class="text-sm mt-2">No Count</p>
24				</div>
25				<div class="text-center">
26					<Avatar 
27						showNotification 
28						notificationCount={3}
29						src={users[1].image} 
30						alt="User" 
31						fallback="NC" 
32						size="xl" 
33					/>
34					<p class="text-sm mt-2">Count: 3</p>
35				</div>
36				<div class="text-center">
37					<Avatar 
38						showNotification 
39						notificationCount={25}
40						src={users[2].image} 
41						alt="User" 
42						fallback="HC" 
43						size="xl" 
44					/>
45					<p class="text-sm mt-2">Count: 25</p>
46				</div>
47				<div class="text-center">
48					<Avatar 
49						showNotification 
50						notificationCount={150}
51						src={users[3].image} 
52						alt="User" 
53						fallback="OF" 
54						size="xl" 
55					/>
56					<p class="text-sm mt-2">Count: 99+</p>
57				</div>
58			</div>

Combined Features

Combine status indicators, notifications, borders, and colors for rich user presence display.

Online + Badge

Bordered + Busy

All Features

Rounded + All

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6        { name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7        { name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8        { name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9        { name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10        { name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11    ];
12</script>
13
14    <div class="flex flex-wrap gap-6">
15        <div class="text-center">
16            <Avatar
17                src={users[0].image}
18                alt="Bordered Circle"
19                fallback="BC"
20                variant="bordered"
21                size="xl"
22            />
23            <p class="text-sm mt-2">Bordered Circle</p>
24        </div>
25        <div class="text-center">
26            <Avatar
27                shape="square"
28                variant="bordered"
29                color="primary"
30                fallback="SB"
31                size="xl"
32            />
33            <p class="text-sm mt-2">Square Bordered</p>
34        </div>
35        <div class="text-center">
36            <Avatar
37                shape="rounded"
38                variant="solid"
39                color="gradient"
40                fallback="GR"
41                size="xl"
42            />
43            <p class="text-sm mt-2">Rounded Gradient</p>
44        </div>
45        <div class="text-center">
46            <Avatar
47                shape="square"
48                color="red"
49                fallback="SD"
50                size="xl"
51            />
52            <p class="text-sm mt-2">Square Red</p>
53        </div>
54    </div>

Avatar Groups

Default spacing

Tight spacing

Loose spacing

Large size group

Colored avatars group

Code Svelte

1
2<script lang="ts">
3	import { Avatar, AvatarPrimitives, Card } from "@kareyes/aether";
4
5	const users = [
6		{ name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7		{ name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8		{ name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9		{ name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10		{ name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11	];
12
13	const team = [
14		{ name: "Sarah Connor", role: "Designer", color: "primary" as const },
15		{ name: "Michael Scott", role: "Manager", color: "green" as const },
16		{ name: "Pam Beesly", role: "Developer", color: "purple" as const },
17		{ name: "Jim Halpert", role: "Sales", color: "blue" as const },
18	];
19    </script>
20        <div class="space-y-6">
21            <div>
22                <p class="text-sm text-muted-foreground mb-3">Default spacing</p>
23                <AvatarPrimitives.AvatarGroup>
24                    {#each users as user}
25                        <Avatar 
26                            src={user.image} 
27                            alt={user.name} 
28                            fallback={user.name}
29                            variant="bordered"
30                        />
31                    {/each}
32                </AvatarPrimitives.AvatarGroup>
33            </div>
34
35            <div>
36                <p class="text-sm text-muted-foreground mb-3">Tight spacing</p>
37                <AvatarPrimitives.AvatarGroup spacing="tight">
38                    {#each users as user}
39                        <Avatar 
40                            src={user.image} 
41                            alt={user.name} 
42                            fallback={user.name}
43                            variant="bordered"
44                            color="green"
45                        />
46                    {/each}
47                </AvatarPrimitives.AvatarGroup>
48            </div>
49
50            <div>
51                <p class="text-sm text-muted-foreground mb-3">Loose spacing</p>
52                <AvatarPrimitives.AvatarGroup spacing="loose">
53                    {#each users.slice(0, 3) as user}
54                        <Avatar 
55                            src={user.image} 
56                            alt={user.name} 
57                            fallback={user.name}
58                            variant="bordered"
59                        />
60                    {/each}
61                </AvatarPrimitives.AvatarGroup>
62            </div>
63
64            <div>
65                <p class="text-sm text-muted-foreground mb-3">Large size group</p>
66                <AvatarPrimitives.AvatarGroup>
67                    {#each users.slice(0, 4) as user}
68                        <Avatar 
69                            src={user.image} 
70                            alt={user.name} 
71                            fallback={user.name}
72                            variant="bordered"
73                            size="lg"
74                        />
75                    {/each}
76                </AvatarPrimitives.AvatarGroup>
77            </div>
78
79            <div>
80                <p class="text-sm text-muted-foreground mb-3">Colored avatars group</p>
81                <AvatarPrimitives.AvatarGroup>
82                    {#each team as member}
83                        <Avatar 
84                            fallback={member.name}
85                            color={member.color}
86                            variant="bordered"
87                        />
88                    {/each}
89                </AvatarPrimitives.AvatarGroup>
90            </div>
91        </div>
92

User Cards

Sarah Connor

Designer

Michael Scott

Manager

Pam Beesly

Developer

Jim Halpert

Sales

Code Svelte

1
2<script lang="ts">
3    import { Avatar, Card } from "@kareyes/aether";
4
5    const team = [
6        { name: "Sarah Connor", role: "Designer", color: "primary" as const },
7        { name: "Michael Scott", role: "Manager", color: "green" as const },
8        { name: "Pam Beesly", role: "Developer", color: "purple" as const },
9        { name: "Jim Halpert", role: "Sales", color: "blue" as const },
10        { name: "Dwight Schrute", role: "Assistant to the Regional Manager", color: "yellow" as const },
11        { name: "Angela Martin", role: "Accountant", color: "pink" as const },
12    ];
13</script>
14
15    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
16        {#each team as member, i}
17            <div class="p-4 border rounded-lg flex items-center gap-3">
18                <Avatar
19                    fallback={member.name}
20                    color={member.color}
21                    variant="bordered"
22                    size="lg"
23                    status={["online", "busy", "away", "offline"][i] as "online" | "busy" | "away" | "offline"}
24                    showNotification={i % 2 === 0}
25                    notificationCount={i % 2 === 0 ? (i + 1) * 3 : undefined}
26                />
27                <div>
28                    <p class="font-medium">{member.name}</p>
29                    <p class="text-sm text-muted-foreground">{member.role}</p>
30                </div>
31            </div>
32        {/each}
33    </div>

Combined Styles

Bordered Circle

Square Bordered

Rounded Gradient

Square Red

Code Svelte

1
2<script lang="ts">
3    import { Avatar } from "@kareyes/aether";
4
5    const users = [
6		{ name: "John Doe", image: "https://i.pravatar.cc/150?img=1" },
7		{ name: "Jane Smith", image: "https://i.pravatar.cc/150?img=2" },
8		{ name: "Bob Johnson", image: "https://i.pravatar.cc/150?img=3" },
9		{ name: "Alice Williams", image: "https://i.pravatar.cc/150?img=4" },
10		{ name: "Charlie Brown", image: "https://i.pravatar.cc/150?img=5" },
11	];
12</script>
13    <div class="flex flex-wrap gap-6">
14        <div class="text-center">
15            <Avatar 
16                status="online"
17                showNotification
18                notificationCount={5}
19                src={users[0].image} 
20                alt="User" 
21                fallback="ON" 
22                size="xl" 
23            />
24            <p class="text-sm mt-2">Online + Badge</p>
25        </div>
26        <div class="text-center">
27            <Avatar 
28                variant="bordered"
29                color="primary"
30                status="busy"
31                src={users[1].image} 
32                alt="User" 
33                fallback="BS" 
34                size="xl" 
35            />
36            <p class="text-sm mt-2">Bordered + Busy</p>
37        </div>
38        <div class="text-center">
39            <Avatar 
40                variant="bordered"
41                color="green"
42                status="away"
43                showNotification
44                notificationCount={12}
45                src={users[2].image} 
46                alt="User" 
47                fallback="AF" 
48                size="xl" 
49            />
50            <p class="text-sm mt-2">All Features</p>
51        </div>
52        <div class="text-center">
53            <Avatar 
54                shape="rounded"
55                variant="bordered"
56                color="purple"
57                status="online"
58                showNotification
59                notificationCount={99}
60                src={users[3].image} 
61                alt="User" 
62                fallback="RA" 
63                size="xl" 
64            />
65            <p class="text-sm mt-2">Rounded + All</p>
66        </div>
67    </div>
68

Basic Usage

<script lang="ts">
  import { Avatar } from "@kareyes/aether";
</script>

<Avatar
  src="https://github.com/shadcn.png"
  alt="User"
  fallback="CN"
/>

With Primitives Import

<script lang="ts">
  import { AvatarPrimitives } from "@kareyes/aether";
</script>

<AvatarPrimitives.Root>
  <AvatarPrimitives.Image src="https://github.com/shadcn.png" alt="User" />
  <AvatarPrimitives.Fallback>CN</AvatarPrimitives.Fallback>
</AvatarPrimitives.Root>

Components

Component	Description
`Avatar`	Enhanced wrapper with variants and colors
`AvatarGroup`	Container for overlapping avatar displays
`Root`	Base avatar container
`Image`	Avatar image element
`Fallback`	Fallback content when image fails

Props Reference

Avatar

Prop	Type	Default	Description
`src`	`string`	-	Image source URL
`alt`	`string`	`""`	Image alt text
`fallback`	`string`	-	Text for fallback initials
`size`	`"xs" \| "sm" \| "default" \| "lg" \| "xl" \| "2xl"`	`"default"`	Avatar size
`shape`	`"circle" \| "square" \| "rounded"`	`"circle"`	Avatar shape
`variant`	`"default" \| "bordered" \| "solid"`	`"default"`	Visual variant
`color`	`"default" \| "primary" \| "secondary" \| "green" \| "yellow" \| "red" \| "blue" \| "purple" \| "pink" \| "gradient"`	`"default"`	Fallback color
`class`	`string`	-	Additional CSS classes for root
`imageClass`	`string`	-	Additional CSS classes for image
`fallbackClass`	`string`	-	Additional CSS classes for fallback
`customFallback`	`Snippet`	-	Custom fallback snippet
`delayMs`	`number`	`0`	Delay before showing fallback

AvatarGroup

Prop	Type	Default	Description
`max`	`number`	`5`	Maximum avatars to display
`size`	Avatar size type	`"default"`	Size for all avatars
`spacing`	`"tight" \| "default" \| "loose"`	`"default"`	Overlap spacing
`class`	`string`	-	Additional CSS classes
`children`	`Snippet`	Required	Avatar components

Sizes

<Avatar size="xs" fallback="XS" />   <!-- 24px -->
<Avatar size="sm" fallback="SM" />   <!-- 32px -->
<Avatar size="default" fallback="MD" />  <!-- 40px -->
<Avatar size="lg" fallback="LG" />   <!-- 48px -->
<Avatar size="xl" fallback="XL" />   <!-- 56px -->
<Avatar size="2xl" fallback="2X" />  <!-- 64px -->

Shapes

<Avatar shape="circle" fallback="CI" />
<Avatar shape="rounded" fallback="RO" />
<Avatar shape="square" fallback="SQ" />

Variants

Default

<Avatar variant="default" fallback="DF" />

Bordered

Adds a ring with offset around the avatar:

<Avatar variant="bordered" fallback="BO" />

Solid

<Avatar variant="solid" fallback="SO" />

Colors

Available for fallback backgrounds:

<Avatar color="default" fallback="DF" />
<Avatar color="primary" fallback="PR" />
<Avatar color="secondary" fallback="SE" />
<Avatar color="green" fallback="GR" />
<Avatar color="yellow" fallback="YE" />
<Avatar color="red" fallback="RE" />
<Avatar color="blue" fallback="BL" />
<Avatar color="purple" fallback="PU" />
<Avatar color="pink" fallback="PI" />
<Avatar color="gradient" fallback="GD" />

Examples

With Fallback Text

<Avatar fallback="John Doe" />
<!-- Displays: "JD" -->

Without Image (Icon Fallback)

<Avatar />
<!-- Displays default user icon -->

Bordered with Colors

<Avatar variant="bordered" color="primary" fallback="PR" size="lg" />
<Avatar variant="bordered" color="green" fallback="GR" size="lg" />
<Avatar variant="bordered" color="red" fallback="RE" size="lg" />

Custom Fallback

<Avatar>
  {#snippet customFallback()}
    <span class="text-2xl">🎨</span>
  {/snippet}
</Avatar>

Avatar Groups

<script lang="ts">
  import { Avatar, AvatarGroup } from "@kareyes/aether";

  const users = [
    { image: "/avatar1.jpg", name: "User 1" },
    { image: "/avatar2.jpg", name: "User 2" },
    { image: "/avatar3.jpg", name: "User 3" },
  ];
</script>

<AvatarGroup spacing="default">
  {#each users as user}
    <Avatar src={user.image} alt={user.name} fallback={user.name} />
  {/each}
</AvatarGroup>

Spacing Options

<AvatarGroup spacing="tight">...</AvatarGroup>   <!-- Less overlap -->
<AvatarGroup spacing="default">...</AvatarGroup> <!-- Standard overlap -->
<AvatarGroup spacing="loose">...</AvatarGroup>   <!-- Minimal overlap -->

User Profile Card

<script lang="ts">
  import { Avatar } from "@kareyes/aether";
</script>

<div class="flex items-center gap-4">
  <Avatar
    src={user.avatar}
    fallback={user.name}
    size="xl"
    variant="bordered"
    color="primary"
  />
  <div>
    <h3 class="font-semibold">{user.name}</h3>
    <p class="text-sm text-muted-foreground">{user.email}</p>
  </div>
</div>

Online Status Indicator

<div class="relative inline-block">
  <Avatar src={user.avatar} fallback={user.name} size="lg" />
  <span
    class="absolute bottom-0 right-0 block size-3 rounded-full bg-green-500 ring-2 ring-background"
  ></span>
</div>

Team Members Grid

<script lang="ts">
  import { Avatar } from "@kareyes/aether";
</script>

<div class="grid grid-cols-4 gap-4">
  {#each team as member}
    <div class="text-center">
      <Avatar
        src={member.avatar}
        fallback={member.name}
        size="2xl"
        variant="bordered"
        color={member.color}
        class="mx-auto"
      />
      <p class="mt-2 text-sm font-medium">{member.name}</p>
      <p class="text-xs text-muted-foreground">{member.role}</p>
    </div>
  {/each}
</div>

How Initials Are Generated

The component automatically extracts initials from the fallback text:

Takes the first letter of each word
Converts to uppercase
Limits to 2 characters maximum

Examples:

"John Doe" → "JD"
"Sarah" → "SA"
"John Paul Smith" → "JP"

Image Loading Behavior

If src is provided, attempts to load the image
If image fails or is loading, shows fallback
Fallback priority:
- Custom snippet (customFallback)
- Generated initials (from fallback text)
- Default user icon

Accessibility

The Avatar component follows accessibility best practices:

ARIA Attributes

Images include alt text for screen readers
Fallback text is semantic and readable
Proper ARIA attributes from underlying bits-ui components

Best Practices

Always provide alt text: Describe who the avatar represents
Use meaningful fallbacks: Provide name for initials generation
Color contrast: All colors meet WCAG guidelines
Test with screen readers: Ensure announcements are clear