Avatar

Image with a built-in fallback. Pairs AvatarImage with AvatarFallback — the fallback shows whenever the image is missing, loading, or errors. Static — the badge, group, and group-count slots compose on top.

API Reference Component Source

Basic

avatar.svelte

<script lang="ts">
	import * as Avatar from '$lib/components/ui/avatar';
</script>

<Avatar.Root>
	<Avatar.Image src="https://github.com/vercel.png" alt="@vercel" />
	<Avatar.Fallback>VC</Avatar.Fallback>
</Avatar.Root>

Sizes

avatar.svelte

<script lang="ts" module>
	export type AvatarSize = 'default' | 'sm' | 'lg';
	export type AvatarVariant = 'default' | 'gradient';
</script>

<script lang="ts">
	import { Avatar as AvatarPrimitive } from 'bits-ui';
	import { cn } from '$lib/utils.js';
	import { gradientFromSeed } from './gradient.js';

	let {
		ref = $bindable(null),
		loadingStatus = $bindable('loading'),
		size = 'default',
		variant = 'default',
		seed,
		class: className,
		...restProps
	}: AvatarPrimitive.RootProps & {
		size?: AvatarSize;
		variant?: AvatarVariant;
		seed?: string;
	} = $props();

	const gradient = $derived(variant === 'gradient' && seed ? gradientFromSeed(seed) : null);
</script>

<AvatarPrimitive.Root
	{...restProps}
	bind:ref
	bind:loadingStatus
	data-slot="avatar"
	data-size={size}
	data-variant={variant}
	class={cn(
		'group/avatar relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:border-border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten',
		className
	)}
	style={gradient ? `background: ${gradient}` : undefined}
/>

Gradient

Set variant="gradient" with a stable seed string (user id, handle, or any unique key) to render a deterministic two-stop gradient. Hierarchy comes from chroma + size, not heavy weight — the letter sits on the gradient at default weight.

avatar-gradient.svelte

<Avatar.Root variant="gradient" seed="alex.cohen">
	<Avatar.Fallback>AC</Avatar.Fallback>
</Avatar.Root>

<Avatar.Root variant="gradient" seed="margot.k">
	<Avatar.Fallback>MK</Avatar.Fallback>
</Avatar.Root>

<Avatar.Root variant="gradient" seed="bloom-nx">
	<Avatar.Fallback>BX</Avatar.Fallback>
</Avatar.Root>

With status badge

avatar.svelte

<script lang="ts" module>
	export type AvatarSize = 'default' | 'sm' | 'lg';
	export type AvatarVariant = 'default' | 'gradient';
</script>

<script lang="ts">
	import { Avatar as AvatarPrimitive } from 'bits-ui';
	import { cn } from '$lib/utils.js';
	import { gradientFromSeed } from './gradient.js';

	let {
		ref = $bindable(null),
		loadingStatus = $bindable('loading'),
		size = 'default',
		variant = 'default',
		seed,
		class: className,
		...restProps
	}: AvatarPrimitive.RootProps & {
		size?: AvatarSize;
		variant?: AvatarVariant;
		seed?: string;
	} = $props();

	const gradient = $derived(variant === 'gradient' && seed ? gradientFromSeed(seed) : null);
</script>

<AvatarPrimitive.Root
	{...restProps}
	bind:ref
	bind:loadingStatus
	data-slot="avatar"
	data-size={size}
	data-variant={variant}
	class={cn(
		'group/avatar relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:border-border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten',
		className
	)}
	style={gradient ? `background: ${gradient}` : undefined}
/>

Group

avatar-group.svelte

<Avatar.Group>
	<Avatar.Root>
		<Avatar.Image src="https://github.com/vercel.png" alt="@vercel" />
		<Avatar.Fallback>VC</Avatar.Fallback>
	</Avatar.Root>
	<Avatar.Root>
		<Avatar.Fallback>BL</Avatar.Fallback>
	</Avatar.Root>
	<Avatar.GroupCount>+3</Avatar.GroupCount>
</Avatar.Group>

Avatar.Root props

Inherits from bits-ui Avatar.Root. Image, Fallback, Badge, Group, and GroupCount each accept standard HTML attributes.

Type	Default	Description
`'default' \| 'sm' \| 'lg'`	`'default'`	Sets the avatar diameter via data-size. Group slots inherit this.
`'default' \| 'gradient'`	`'default'`	Visual treatment. Gradient renders a deterministic two-stop surface seeded by the seed prop — used when no image is available.
`string`	—	Stable seed for the gradient (user id, handle). Same seed → same gradient. Required when variant is "gradient".
`'loading' \| 'loaded' \| 'error' (bindable)`	—	Reflects the current image load state. Two-way bindable — read it to sync external UI.
`number`	—	Delay before the fallback renders while the image is loading.
`string`	—	Merged onto the root via tailwind-merge.