Avatar

The Avatar component is a reusable identity primitive that renders a user’s profile image in a consistent circular format. It supports CMS-normalized models and direct src/alt usage, enforces accessible image handling, and gracefully falls back to a default icon when the image is missing or fails to load. Designed to be layout-agnostic and portable across frameworks, it ensures predictable and accessible identity representation across an application.

Preview
Code

import { Avatar } from "@/registry/rokkit200-ui/components/avatar/avatar";

export default function AvatarDefaultDemo() {
    return (
        <Avatar
            size="lg"
            variant="primary"
            src="https://i.pravatar.cc/150?img=3"
            alt="Jane Doe"
        />
    );
}

Usage

import { Avatar } from "@/rokkit200-ui/components/avatar/avatar";

<Avatar
    size="lg"
    variant="primary"
    src="https://i.pravatar.cc/150?img=3"
    alt="Jane Doe"
/>

Examples

Primary

Used as the default visual identity style.

Preview
Code

import { Avatar } from "@/registry/rokkit200-ui/components/avatar/avatar";

export default function AvatarPrimaryDemo() {
    return <Avatar variant={"primary"}></Avatar>;
}

Secondary

Used for lower-emphasis identity contexts.

Preview
Code

import { Avatar } from "@/registry/rokkit200-ui/components/avatar/avatar";

export default function AvatarSecondaryDemo() {
    return <Avatar variant={"secondary"}></Avatar>;
}

Tertiary

Used in minimal or bordered contexts where subtle contrast is required.

Preview
Code

import { Avatar } from "@/registry/rokkit200-ui/components/avatar/avatar";

export default function AvatarTertiaryDemo() {
    return <Avatar variant={"tertiary"}></Avatar>;
}

API Reference

Prop	Type	Default	Description
`model`	`{ src?: string; alt?: string }`	—	CMS-normalized avatar model.
`src`	`string \| null`	—	Image source URL. Overrides `model.src` if provided.
`alt`	`string \| null`	—	Alternative text. Overrides `model.alt` if provided.
`decorative`	`boolean`	`false`	If `true`, forces `alt=""` and treats the avatar as decorative.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number \| string`	`"lg"`	Preset or custom size for width and height.
`variant`	`"primary" \| "secondary" \| "tertiary"`	`"primary"`	Visual color variant.
`fallback`	`React.ReactNode`	—	Custom fallback content when image is missing or fails.
`fallbackIcon`	`React.ReactNode`	Default icon	Convenience override for default SVG fallback icon.
`className`	`string`	—	Additional classes applied to the root element.
`imageClassName`	`string`	—	Additional classes applied to the `<img>` element.
`fallbackClassName`	`string`	—	Additional classes applied to the fallback container.
`fallbackIconWrapperClassName`	`string`	—	Additional classes applied to the fallback icon wrapper `<div>`.

Images are always rendered with loading=“lazy” and decoding=“async” enforced.

SVG URLs are treated as standard image sources.

Direct props (src, alt) take precedence over model values.

Accessibility

Always renders a semantic <img> element when src is present.

If decorative={true}, the avatar renders with alt="".

If not decorative and alt is missing, a development warning is emitted.

Fallback content is marked aria-hidden when decorative.

The component is designed to meet WCAG 2.1 AA requirements when used as intended.

Testimonial

Teams