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

Install the brain, or copy just this primitive in with the CLI.

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.