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
<Avatar.Root>
<Avatar.Fallback>JW</Avatar.Fallback>
</Avatar.Root>Examples
Initials
Initials on the soft accent fill. This is the common case in Statix.
<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).
<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.
<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.
<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.
<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| Prop | Type | Default |
|---|---|---|
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 bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the base classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="avatar" | Always present. |
data-size | sm, default or lg. |
data-status | loading, loaded or error (from bits-ui). |
Avatar.Image
renders<img> and accepts its attributes| Prop | Type | Default |
|---|---|---|
src | string Image URL. | – |
alt * | string Name of the person, or empty. | – |
| Data attribute | Meaning |
|---|---|
data-slot="avatar-image" | Always present. |
Avatar.Fallback
renders<span> and accepts its attributesInitials on primary-soft. Shown until the image loads.
| Data attribute | Meaning |
|---|---|
data-slot="avatar-fallback" | Always present. |
Avatar.Badge
renders<span> and accepts its attributesStatus dot at the bottom right. Sized per avatar size.
| Data attribute | Meaning |
|---|---|
data-slot="avatar-badge" | Always present. |
Avatar.Group
renders<div> and accepts its attributesOverlaps its avatars with a ring in the page background colour.
| Data attribute | Meaning |
|---|---|
data-slot="avatar-group" | Always present. |
Avatar.GroupCount
renders<div> and accepts its attributesCircle with the number of hidden people. Matches the group’s avatar size.
| Data attribute | Meaning |
|---|---|
data-slot="avatar-group-count" | Always present. |