Skip to content
navius

Components / Avatar

Avatar

An image element with a fallback for representing the user.

CT JD
razor
<NaviusAvatar class="... overflow-hidden rounded-full">
    <NaviusAvatarImage Src="/colm.jpg" alt="Colm Tuite"
                       class="h-full w-full object-cover" />
    <NaviusAvatarFallback DelayMs="600" class="... bg-accent">
        CT
    </NaviusAvatarFallback>
</NaviusAvatar>

Features

  • Automatic and manual control over when the image renders.
  • Falls back to custom content while the image is loading or on error.
  • Optionally delay the fallback (DelayMs) to avoid a flash on fast connections.
  • Surfaces every loading transition via OnLoadingStatusChange.

Installation

Reference the Navius.Primitives package for the headless primitive, or vendor a styled version with the CLI: navius add copies the styled zits/ui component plus the brain files it depends on.

Terminal bash
navius add avatar

Anatomy

Import the parts and assemble them.

razor
@using Navius.Primitives.Components.Avatar

<NaviusAvatar>
    <NaviusAvatarImage />
    <NaviusAvatarFallback />
</NaviusAvatar>

API Reference

Root

Contains all the parts of an avatar. Renders a span.

Prop Type Default
ChildContent RenderFragment? -

Image

The image to render. By default it only renders once it has loaded; while loading and on error it is hidden so the fallback can show. Renders an img.

Prop Type Default
Src string? -
OnLoadingStatusChange EventCallback<string> -

Data attributes

Data attribute Values
[data-navius-avatar-image] Present on the image

Fallback

An element that renders when the image has not loaded, meaning while it is loading or on error. Renders a span.

Prop Type Default
DelayMs int 0
ChildContent RenderFragment? -

Data attributes

Data attribute Values
[data-navius-avatar-fallback] Present on the fallback

Accessibility

Follows the WAI image guidance. The Image part renders a native <img>, so pass an alt describing the user; the Fallback's text content is read in its place when no image loads.

Keyboard interactions

Avatar is presentational and not focusable, so it exposes no keyboard interactions of its own.