Skip to content
Statix Design System

Display

Avatar

Round picture or initials for a person, such as the customer in the top bar or Jonas Weber in the support row.

import * as Avatar from '@statix/ui/avatar';

Playground

JW
Controls
<Avatar.Root>
	<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>

Examples

Initials

Initials on the soft accent fill. This is the common case in Statix.

LB
JW
<script lang="ts">
	import * as Avatar from '@statix/ui/avatar';
</script>

<Avatar.Root>
	<Avatar.Fallback>LB</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root>
	<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>

Sizes

sm (32px), default (40px, top bar) and lg (56px, support row).

JW
JW
JW
<script lang="ts">
	import * as Avatar from '@statix/ui/avatar';
</script>

<Avatar.Root size="sm">
	<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root>
	<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="lg">
	<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>

With an image

Avatar.Image shows once it has loaded. Until then, and if it fails, the fallback shows.

LB
JW
<script lang="ts">
	import * as Avatar from '@statix/ui/avatar';
</script>

<Avatar.Root size="lg">
	<Avatar.Image src="https://github.com/shadcn.png" alt="Lena Berger" />
	<Avatar.Fallback>LB</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="lg">
	<Avatar.Image src="/missing-photo.jpg" alt="Jonas Weber" />
	<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>

Support contact

The large avatar next to a name and opening hours, as at the bottom of the start page.

Questions or a broken website?

Jonas Weber helps. Mon to Fri, 8 am to 8 pm.

<script lang="ts">
	import * as Avatar from '@statix/ui/avatar';
</script>

<div class="flex w-full max-w-md items-center gap-4">
	<Avatar.Root size="lg">
		<Avatar.Fallback aria-hidden="true">JW</Avatar.Fallback>
	</Avatar.Root>
	<div>
		<p class="text-subtitle font-semibold text-ink">Questions or a broken website?</p>
		<p class="text-ink-2">Jonas Weber helps. Mon to Fri, 8 am to 8 pm.</p>
	</div>
</div>

Group

Overlapping avatars with a count, for shared access to a website.

LB
MK
JW
+2
5 people can edit yoga-berger.de
<script lang="ts">
	import * as Avatar from '@statix/ui/avatar';
</script>

<div class="flex items-center gap-3">
	<Avatar.Group>
		<Avatar.Root>
			<Avatar.Fallback>LB</Avatar.Fallback>
		</Avatar.Root>
		<Avatar.Root>
			<Avatar.Fallback>MK</Avatar.Fallback>
		</Avatar.Root>
		<Avatar.Root>
			<Avatar.Fallback>JW</Avatar.Fallback>
		</Avatar.Root>
		<Avatar.GroupCount>+2</Avatar.GroupCount>
	</Avatar.Group>
	<span class="text-small text-muted-foreground">5 people can edit yoga-berger.de</span>
</div>

With a status badge

Avatar.Badge marks someone as available. It is green by default.

JW
JW
JW
<script lang="ts">
	import * as Avatar from '@statix/ui/avatar';
</script>

<Avatar.Root size="lg">
	<Avatar.Fallback>JW</Avatar.Fallback>
	<Avatar.Badge />
</Avatar.Root>
<Avatar.Root>
	<Avatar.Fallback>JW</Avatar.Fallback>
	<Avatar.Badge />
</Avatar.Root>
<Avatar.Root size="sm">
	<Avatar.Fallback>JW</Avatar.Fallback>
	<Avatar.Badge class="bg-muted-foreground" />
</Avatar.Root>

Guidelines

Do

  • Use two initials, first and last name: "JW" for Jonas Weber.
  • Show the name next to the avatar wherever there is room.

Don't

  • Don’t use avatars for companies or products. Use an icon tile instead.
  • Don’t pick other colours per person. All avatars use the same soft accent.

Accessibility

  • Give Avatar.Image an alt text with the person’s name, or alt="" when the name is next to it.
  • Initials are read out letter by letter. When the name is not visible, add it with aria-label on Avatar.Root and aria-hidden on the fallback.
  • Avatar.Badge is decorative. Say the status in text as well, for example in a tooltip or sr-only span.

API reference

Avatar.Root

renders <span> and accepts its attributes
PropTypeDefault
size 'sm' | 'default' | 'lg'

Diameter: 32, 40 or 56px.

'default'
loadingStatus bind'loading' | 'loaded' | 'error'

Image loading state from bits-ui.

–
delayMs number

Wait before showing the fallback, to avoid a flash on fast connections.

0
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the base classes; yours win.

–
Data attributeMeaning
data-slot="avatar"Always present.
data-sizesm, default or lg.
data-statusloading, loaded or error (from bits-ui).

Avatar.Image

renders <img> and accepts its attributes
PropTypeDefault
src string

Image URL.

–
alt * string

Name of the person, or empty.

–
Data attributeMeaning
data-slot="avatar-image"Always present.

Avatar.Fallback

renders <span> and accepts its attributes

Initials on primary-soft. Shown until the image loads.

Data attributeMeaning
data-slot="avatar-fallback"Always present.

Avatar.Badge

renders <span> and accepts its attributes

Status dot at the bottom right. Sized per avatar size.

Data attributeMeaning
data-slot="avatar-badge"Always present.

Avatar.Group

renders <div> and accepts its attributes

Overlaps its avatars with a ring in the page background colour.

Data attributeMeaning
data-slot="avatar-group"Always present.

Avatar.GroupCount

renders <div> and accepts its attributes

Circle with the number of hidden people. Matches the group’s avatar size.

Data attributeMeaning
data-slot="avatar-group-count"Always present.