Data

Avatar

Renders a user avatar image with consumer-provided fallback content.

idle

Usage

import {
	Avatar,
	AvatarCharacter,
	AvatarFallback,
	AvatarImage,
} from "@mizen-labs/ui";

Anatomy

The parts and how they nest, taken from the preview above.

<Avatar>
	<AvatarImage />
	<AvatarFallback />
</Avatar>
<Avatar>
	<AvatarImage />
	<AvatarFallback />
</Avatar>
<Avatar>
	<AvatarImage />
	<AvatarFallback />
</Avatar>
<AvatarCharacter />

Examples

Generated characters

Simple faces derived from stable identity seeds. Shapes, colors, and expressions stay consistent in both themes.

Generated image fallback

Use a generated character when a profile photo cannot load.

Project owner

Sizes

Avatar scales across small, default, and large dimensions with proportional typography.

Image and fallback

Avatar displays a loaded user image and falls back to consumer-supplied content on error.

Recommendations

Guidance	Practice
Do	Provide recognizable fallback content and useful image descriptions. Keep sizes consistent within the same context.

Usage boundaries

Guidance	Boundary
Scope	Use Thumbnail for general media. An avatar should not be the only visible identifier for a person.

API reference

Public props from @mizen-labs/ui. Use exported prop types for the complete TypeScript contract.

Avatar, AvatarImage, AvatarFallback

Image avatars with optional colored fallback content.

Prop	Type	Default	Description
`size`	`"default" \| "lg" \| "sm"`	`"default"`	Sets the avatar dimensions.
`color`	`"neutral" \| "blue" \| "purple" \| "green" \| "orange"`	`"neutral"`	AvatarFallback identity color. Keep the same color for each source.
`alt`	`string`	`—`	Required text alternative describing the avatar image.
`keepMounted`	`boolean`	`false`	Keeps the image element mounted while loading or after an error.
`onLoadingStatusChange`	`(status: "idle" \| "loading" \| "loaded" \| "error") => void`	`—`	Callback fired when the image loading status changes.
`delay`	`number`	`0`	Delay in milliseconds before displaying the fallback content.

AvatarCharacter

Standalone SVG character. Import from @mizen-labs/ui or @mizen-labs/ui/avatar. Same exact seed produces the same design without storage, network calls, or random state. Designs can repeat across seeds. Omit label beside visible identity text.

Prop	Type	Default	Description
`seed`	`string`	`Required`	Stable identity key. Prefer an immutable user ID. Seeds are case-sensitive.
`size`	`"sm" \| "default" \| "lg"`	`"default"`	24px, 32px, or 40px character.
`label`	`string`	`—`	Accessible image name. Without a label, the character is decorative.