Avatar

Identity marker for people, teams, and entities with automatic image fallback handling and four size options for dense or spacious layouts.

AccessibleDark Mode4 Sizes

Install

$npx react-principles add avatar

Theme Preview

Light

Dark

Live Demo

Open in Storybookopen_in_new

Size

Code Snippet

src/ui/Avatar.tsx

import { Avatar } from "@/ui/Avatar";

<Avatar size="lg">
  <Avatar.Image src="https://i.pravatar.cc/120" alt="Profile" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

Copy-Paste (Single File)

Avatar.tsx

"use client";
/* eslint-disable @next/next/no-img-element */

import { createContext, useContext, useState, type ImgHTMLAttributes, type ReactNode } from "react";
import { cn } from "@/lib/utils";

export type AvatarSize = "sm" | "md" | "lg" | "xl";

export interface AvatarProps {
  size?: AvatarSize;
  className?: string;
  children?: ReactNode;
}

Props

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg" \| "xl"`	`"md"`	Controls the avatar diameter and fallback text size.
`className`	`string`	`—`	Additional classes applied to the avatar root.
`children`	`ReactNode`	`—`	Usually composed with Avatar.Image and Avatar.Fallback.
`Avatar.Image`	`ImgHTMLAttributes<HTMLImageElement>`	`—`	Displays the profile image until an error occurs.
`Avatar.Fallback`	`{ className?: string; children: ReactNode }`	`—`	Fallback initials or content shown after image load failure.

react-principles