cotton
Core UI Kit
36

Avatar

Represent a user or entity with an image, initials, or a fallback icon.

Basic Usage

Pass initials to display a text fallback. With no image or initials, a user icon is shown.

JD 
<c-ui.avatar initials="JD" />
<c-ui.avatar />
{% cotton ui.avatar initials="JD" /%}
{% cotton ui.avatar /%}

With Image

Provide a src to render a photo. Always include an alt for accessibility.

Jane Doe 
<c-ui.avatar src="https://i.pravatar.cc/100?img=5" alt="Jane Doe" />
{% cotton ui.avatar src="https://i.pravatar.cc/100?img=5" alt="Jane Doe" /%}

Sizes

Avatars come in sizes from size="xs" to size="xl", defaulting to md.

XS SM MD LG XL 
<c-ui.avatar size="xs" initials="XS" />
<c-ui.avatar size="sm" initials="SM" />
<c-ui.avatar size="md" initials="MD" />
<c-ui.avatar size="lg" initials="LG" />
<c-ui.avatar size="xl" initials="XL" />
{% cotton ui.avatar size="xs" initials="XS" /%}
{% cotton ui.avatar size="sm" initials="SM" /%}
{% cotton ui.avatar size="md" initials="MD" /%}
{% cotton ui.avatar size="lg" initials="LG" /%}
{% cotton ui.avatar size="xl" initials="XL" /%}

Color

Set color to a Tailwind family for a solid background, or color="auto" to derive a stable colour from the initials.

Manual
JD AB CT
Auto (from initials)
SK TC BL KP NV 
{# manually coloured #}
<c-ui.avatar initials="JD" color="blue" />
<c-ui.avatar initials="AB" color="rose" />
<c-ui.avatar initials="CT" color="teal" />

{# auto, derived from the initials #}
<c-ui.avatar initials="SK" color="auto" />
<c-ui.avatar initials="TC" color="auto" />
<c-ui.avatar initials="BL" color="auto" />
<c-ui.avatar initials="KP" color="auto" />
<c-ui.avatar initials="NV" color="auto" />
{# manually coloured #}
{% cotton ui.avatar initials="JD" color="blue" /%}
{% cotton ui.avatar initials="AB" color="rose" /%}
{% cotton ui.avatar initials="CT" color="teal" /%}

{# auto, derived from the initials #}
{% cotton ui.avatar initials="SK" color="auto" /%}
{% cotton ui.avatar initials="TC" color="auto" /%}
{% cotton ui.avatar initials="BL" color="auto" /%}
{% cotton ui.avatar initials="KP" color="auto" /%}
{% cotton ui.avatar initials="NV" color="auto" /%}

Group

Wrap avatars in <c-ui.avatar.group> to stack them with an overlapping ring. Add a trailing avatar to show an overflow count.

Jane Doe AB Sam Lee +3 
<c-ui.avatar.group>
    <c-ui.avatar src="https://i.pravatar.cc/100?img=5" alt="Jane Doe" />
    <c-ui.avatar initials="AB" />
    <c-ui.avatar src="https://i.pravatar.cc/100?img=12" alt="Sam Lee" />
    <c-ui.avatar initials="+3" />
</c-ui.avatar.group>
{% cotton ui.avatar.group %}
    {% cotton ui.avatar src="https://i.pravatar.cc/100?img=5" alt="Jane Doe" /%}
    {% cotton ui.avatar initials="AB" /%}
    {% cotton ui.avatar src="https://i.pravatar.cc/100?img=12" alt="Sam Lee" /%}
    {% cotton ui.avatar initials="+3" /%}
{% endcotton %}

Status Dot

The default slot renders on top of the avatar, so you can position a status indicator over it.

Online user 
<c-ui.avatar src="https://i.pravatar.cc/100?img=8" alt="Online user">
    <span class="absolute bottom-0 right-0 size-2.5 rounded-full bg-green-500 ring-2 ring-white dark:ring-ink-900"></span>
</c-ui.avatar>
{% cotton ui.avatar src="https://i.pravatar.cc/100?img=8" alt="Online user" %}
    <span class="absolute bottom-0 right-0 size-2.5 rounded-full bg-green-500 ring-2 ring-white dark:ring-ink-900"></span>
{% endcotton %}

API Reference

Avatar

Name Description Type Options Default
src Image URL. When set, the avatar renders the image. str —
alt Alternative text for the image. str —
initials Text fallback shown when no image is provided. str —
size Avatar size from xs to xl. str
xssmmdlgxl
md
color Solid background: a Tailwind family (e.g. blue) or 'auto' to derive one from the initials. Empty for neutral. str —
class Additional classes merged onto the avatar element. str —

Avatar Slots

Name Description Type Options Default
slot (default) Rendered on top of the avatar, useful for a status dot or overlay. — —

Avatar.Group

Name Description Type Options Default
class Additional classes merged onto the group wrapper. str —
slot (default) The avatars to stack. — —
Theme
Accent
Ink