M
Marai.UI v1.0.0-alpha.7

Avatar

A composable user identity component. Handles image loading, fallback content, and optional status indicator — style everything via Tailwind CSS using the Class parameter.

Overview

MAvatar manages image loading and fallback resolution. When a Src is provided it renders an <img>; on load failure it shows the Fallback slot. An optional status dot is rendered when Status is set.

The component applies zero default styling. Dimensions, shape, colors, and layout are all controlled by the developer through the Class, ImageClass, FallbackClass, and StatusClass parameters.

Usage

Add the namespace import to use the component.

razor 
@using Marai.UI.Components.MAvatar

Basic Usage

Avatar with an image, with initials, and an empty styled container:

Preview
Jane Doe
razor 
@using Marai.UI.Components.MAvatar

<div class="flex items-center gap-4">
    <MAvatar Src="https://i.pravatar.cc/150?img=1"
             Alt="Jane Doe"
             Class="relative h-10 w-10 shrink-0 overflow-hidden rounded-full"
             ImageClass="h-full w-full object-cover" />

    <MAvatar Class="relative h-10 w-10 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback>
            <span class="text-sm font-medium text-slate-600">JD</span>
        </Fallback>
    </MAvatar>

    <MAvatar Class="relative h-10 w-10 shrink-0 overflow-hidden rounded-full bg-slate-100" />
</div>

Examples

Sizes

Apply any size by setting Tailwind dimension utilities on the Class parameter. The examples below use h-6 w-6 through h-16 w-16.

Preview
razor 
@using Marai.UI.Components.MAvatar

<div class="flex items-center gap-4">
    <MAvatar Class="relative h-6 w-6 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-xs font-medium text-slate-600">XS</span></Fallback>
    </MAvatar>
    <MAvatar Class="relative h-8 w-8 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-sm font-medium text-slate-600">SM</span></Fallback>
    </MAvatar>
    <MAvatar Class="relative h-10 w-10 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-sm font-medium text-slate-600">MD</span></Fallback>
    </MAvatar>
    <MAvatar Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-base font-medium text-slate-600">LG</span></Fallback>
    </MAvatar>
    <MAvatar Class="relative h-16 w-16 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-lg font-medium text-slate-600">XL</span></Fallback>
    </MAvatar>
</div>
Tailwind classes Dimensions Typical use
h-6 w-6 24 × 24 px Compact lists, inline mentions
h-8 w-8 32 × 32 px Comments, chat threads
h-10 w-10 40 × 40 px Navigation bars, standard usage
h-12 w-12 48 × 48 px Profile cards, team lists
h-16 w-16 64 × 64 px Profile pages, account settings

Shapes

Pass rounded-full for a circle or rounded-lg for a rounded square via the Class parameter. Any Tailwind rounded-* value is supported.

Preview
razor 
@using Marai.UI.Components.MAvatar

<div class="flex items-center gap-4">
    <MAvatar Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-base font-medium text-slate-600">AB</span></Fallback>
    </MAvatar>
    <MAvatar Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-lg bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-base font-medium text-slate-600">AB</span></Fallback>
    </MAvatar>
</div>

Fallback Behavior

The component resolves display content in this order:

  1. Render the image when Src is set and loads successfully.
  2. Render the Fallback slot content when the image is missing or fails to load.
  3. Render nothing when neither Src nor Fallback is provided — the styled container remains visible.
Preview
Alex Kim
razor 
@using Marai.UI.Components.MAvatar

<div class="flex items-center gap-4">
    @* Image present — renders the image *@
    <MAvatar Src="https://i.pravatar.cc/150?img=5"
             Alt="Alex Kim"
             Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-full"
             ImageClass="h-full w-full object-cover" />

    @* Initials fallback *@
    <MAvatar Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-full bg-slate-200"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-base font-medium text-slate-600">AK</span></Fallback>
    </MAvatar>

    @* Invalid src — falls back to initials *@
    <MAvatar Src="/invalid-image.png"
             Alt=""
             Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-full bg-slate-200"
             ImageClass="h-full w-full object-cover"
             FallbackClass="flex h-full w-full items-center justify-center">
        <Fallback><span class="text-base font-medium text-slate-600">AK</span></Fallback>
    </MAvatar>

    @* No src, no fallback — empty styled container *@
    <MAvatar Class="relative h-12 w-12 shrink-0 overflow-hidden rounded-full bg-slate-100" />
</div>
Image Error Handling

Image load failure is detected with the browser's native onerror event. In interactive (WebAssembly or Server) render modes the fallback slot is shown automatically on failure. In static server-side rendering, the browser's default broken-image placeholder is shown instead.

Status Indicator

Set the Status parameter to render a presence dot. The dot element carries a data-status attribute (online, away, busy, offline) which you target with Tailwind arbitrary data-attribute variants. Pass positioning, size, ring, and color classes via StatusClass.

Preview
razor 
@using Marai.UI.Components.MAvatar

<div class="flex items-center gap-4">
    @foreach (var (status, label) in new[]
    {
        (AvatarStatus.Online,  "ON"),
        (AvatarStatus.Away,    "AW"),
        (AvatarStatus.Busy,    "BS"),
        (AvatarStatus.Offline, "OF"),
    })
    {
        <MAvatar Status="status"
                 Class="relative h-12 w-12 shrink-0"
                 FallbackClass="flex h-full w-full items-center justify-center rounded-full bg-slate-200"
                 StatusClass="absolute bottom-0 right-0 h-3 w-3 rounded-full ring-2 ring-white data-[status=online]:bg-green-500 data-[status=away]:bg-yellow-400 data-[status=busy]:bg-red-500 data-[status=offline]:bg-slate-400">
            <Fallback><span class="text-base font-medium text-slate-600">@label</span></Fallback>
        </MAvatar>
    }
</div>
Status data-status value Meaning
Online "online" User is active and available
Away "away" User is idle or stepped away
Busy "busy" User is occupied and unavailable
Offline "offline" User is not connected

data-state Reference

The root <div> exposes a data-state attribute that reflects the current image loading state. Use it with Tailwind arbitrary variants to style the container conditionally.

Value Condition
"has-image" Src provided and loaded successfully
"no-image" No Src provided
"error" Src provided but failed to load

Accessibility

  • Set Alt to a meaningful description when the avatar conveys information (e.g., the user's name). Screen readers read the alt attribute from the underlying <img> element.
  • Leave Alt empty (Alt="") or omit it when the avatar is decorative and the user's name appears elsewhere on the page — this prevents redundant announcements.
  • The fallback wrapper receives aria-hidden="true" when Alt is empty, preventing initials or other fallback content from being announced by screen readers.
  • The status dot is always aria-hidden="true". Convey presence state in text if it is meaningful to screen reader users.
  • Additional ARIA attributes (aria-label, role, etc.) can be applied via AdditionalAttributes passthrough.

API Reference

Parameter Type Default Description
Src string? null URL or path of the profile image. When null or empty the fallback is shown immediately.
Alt string? null Alt text for the image. Use an empty string for decorative usage.
Fallback RenderFragment? null Content shown when the image is absent or fails to load — typically one or two initials.
Status AvatarStatus? null When set, renders a presence dot with data-status: Online, Away, Busy, or Offline.
Class string? null CSS classes for the root container. Use Tailwind to set dimensions, shape, overflow, and background.
ImageClass string? null CSS classes for the <img> element. Typically h-full w-full object-cover.
FallbackClass string? null CSS classes for the fallback wrapper <span>. Use to center and size fallback content.
StatusClass string? null CSS classes for the status dot <span>. Include positioning, size, ring, and data-[status=*]: color variants.
AdditionalAttributes Dictionary<string, object>? null Arbitrary HTML attributes forwarded to the root element.