- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
type ImageLoadingStatus = "idle" | "loading" | "loaded" | "error";
function useImageLoadingStatus(
src: string | undefined,
referrerPolicy: React.HTMLAttributeReferrerPolicy | undefined
): ImageLoadingStatus {
const [status, setStatus] = React.useState<ImageLoadingStatus>("idle");
React.useEffect(() => {
if (!src) {
setStatus("error");
return;
}
let isMounted = true;
const image = new window.Image();
const update = (next: ImageLoadingStatus) => () => {
if (isMounted) {
setStatus(next);
}
};
setStatus("loading");
image.onload = update("loaded");
image.onerror = update("error");
if (referrerPolicy) {
image.referrerPolicy = referrerPolicy;
}
image.src = src;
return () => {
isMounted = false;
};
}, [src, referrerPolicy]);
return status;
}
interface AvatarContextValue {
imageLoadingStatus: ImageLoadingStatus;
onImageLoadingStatusChange: (status: ImageLoadingStatus) => void;
}
const AvatarContext = React.createContext<AvatarContextValue | null>(null);
function useAvatarContext(component: string): AvatarContextValue {
const ctx = React.useContext(AvatarContext);
if (!ctx) {
throw new Error(`${component} must be used within Avatar`);
}
return ctx;
}
type AvatarProps = React.ComponentProps<"span"> & {
size?: "default" | "sm" | "lg";
};
function Avatar({
className,
size = "default",
children,
...props
}: AvatarProps) {
const [imageLoadingStatus, setImageLoadingStatus] =
React.useState<ImageLoadingStatus>("idle");
const ctxValue = React.useMemo<AvatarContextValue>(
() => ({
imageLoadingStatus,
onImageLoadingStatusChange: setImageLoadingStatus,
}),
[imageLoadingStatus]
);
return (
<AvatarContext.Provider value={ctxValue}>
<span
className={cn(
"group/avatar after:border-border relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten",
className
)}
data-size={size}
data-slot="avatar"
{...props}
>
{children}
</span>
</AvatarContext.Provider>
);
}
type AvatarImageProps = React.ComponentProps<"img"> & {
onLoadingStatusChange?: (status: ImageLoadingStatus) => void;
};
function AvatarImage({
alt,
className,
onLoadingStatusChange,
referrerPolicy,
src,
...props
}: AvatarImageProps) {
const { onImageLoadingStatusChange } = useAvatarContext("AvatarImage");
const isStringSrc = typeof src === "string";
const imageLoadingStatus = useImageLoadingStatus(
isStringSrc ? src : undefined,
referrerPolicy
);
React.useEffect(() => {
onImageLoadingStatusChange(imageLoadingStatus);
}, [imageLoadingStatus, onImageLoadingStatusChange]);
React.useEffect(() => {
onLoadingStatusChange?.(imageLoadingStatus);
}, [imageLoadingStatus, onLoadingStatusChange]);
if (isStringSrc && imageLoadingStatus !== "loaded") {
return null;
}
return (
<img
alt={alt}
className={cn(
"aspect-square size-full rounded-full object-cover",
className
)}
data-slot="avatar-image"
referrerPolicy={referrerPolicy}
src={src}
{...props}
/>
);
}
function AvatarFallback({ className, ...props }: React.ComponentProps<"span">) {
const { imageLoadingStatus } = useAvatarContext("AvatarFallback");
if (imageLoadingStatus === "loaded") {
return null;
}
return (
<span
className={cn(
"bg-muted text-muted-foreground data-[status=error]:bg-destructive flex size-full items-center justify-center rounded-full text-sm group-data-[size=sm]/avatar:text-xs data-[status=error]:text-white",
className
)}
data-slot="avatar-fallback"
data-status={imageLoadingStatus}
{...props}
/>
);
}
function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
return (
<span
className={cn(
"bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-blend-color ring-2 select-none",
"group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
"group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
"group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
className
)}
data-slot="avatar-badge"
{...props}
/>
);
}
function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"group/avatar-group *:data-[slot=avatar]:ring-background flex -space-x-2 *:data-[slot=avatar]:ring-2",
className
)}
data-slot="avatar-group"
{...props}
/>
);
}
function AvatarGroupCount({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
className={cn(
"bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 items-center justify-center rounded-full text-sm ring-2 group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
className
)}
data-slot="avatar-group-count"
{...props}
/>
);
}
export {
Avatar,
AvatarBadge,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
type AvatarImageProps,
};Avatar renders a circular user image with a text fallback when the image fails to load or is missing. A small composable API covers badges, groups, and counts.
Installation
$ bunx --bun frakment add avatar$ npx frakment add avatar$ pnpm dlx frakment add avatar$ yarn dlx frakment add avatar
Install the following dependencies:
Copy and paste the following code into your project.
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
type ImageLoadingStatus = "idle" | "loading" | "loaded" | "error";
function useImageLoadingStatus(
src: string | undefined,
referrerPolicy: React.HTMLAttributeReferrerPolicy | undefined
): ImageLoadingStatus {
const [status, setStatus] = React.useState<ImageLoadingStatus>("idle");
React.useEffect(() => {
if (!src) {
setStatus("error");
return;
}
let isMounted = true;
const image = new window.Image();
const update = (next: ImageLoadingStatus) => () => {
if (isMounted) {
setStatus(next);
}
};
setStatus("loading");
image.onload = update("loaded");
image.onerror = update("error");
if (referrerPolicy) {
image.referrerPolicy = referrerPolicy;
}
image.src = src;
return () => {
isMounted = false;
};
}, [src, referrerPolicy]);
return status;
}
interface AvatarContextValue {
imageLoadingStatus: ImageLoadingStatus;
onImageLoadingStatusChange: (status: ImageLoadingStatus) => void;
}
const AvatarContext = React.createContext<AvatarContextValue | null>(null);
function useAvatarContext(component: string): AvatarContextValue {
const ctx = React.useContext(AvatarContext);
if (!ctx) {
throw new Error(`${component} must be used within Avatar`);
}
return ctx;
}
type AvatarProps = React.ComponentProps<"span"> & {
size?: "default" | "sm" | "lg";
};
function Avatar({
className,
size = "default",
children,
...props
}: AvatarProps) {
const [imageLoadingStatus, setImageLoadingStatus] =
React.useState<ImageLoadingStatus>("idle");
const ctxValue = React.useMemo<AvatarContextValue>(
() => ({
imageLoadingStatus,
onImageLoadingStatusChange: setImageLoadingStatus,
}),
[imageLoadingStatus]
);
return (
<AvatarContext.Provider value={ctxValue}>
<span
className={cn(
"group/avatar after:border-border relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten",
className
)}
data-size={size}
data-slot="avatar"
{...props}
>
{children}
</span>
</AvatarContext.Provider>
);
}
type AvatarImageProps = React.ComponentProps<"img"> & {
onLoadingStatusChange?: (status: ImageLoadingStatus) => void;
};
function AvatarImage({
alt,
className,
onLoadingStatusChange,
referrerPolicy,
src,
...props
}: AvatarImageProps) {
const { onImageLoadingStatusChange } = useAvatarContext("AvatarImage");
const isStringSrc = typeof src === "string";
const imageLoadingStatus = useImageLoadingStatus(
isStringSrc ? src : undefined,
referrerPolicy
);
React.useEffect(() => {
onImageLoadingStatusChange(imageLoadingStatus);
}, [imageLoadingStatus, onImageLoadingStatusChange]);
React.useEffect(() => {
onLoadingStatusChange?.(imageLoadingStatus);
}, [imageLoadingStatus, onLoadingStatusChange]);
if (isStringSrc && imageLoadingStatus !== "loaded") {
return null;
}
return (
<img
alt={alt}
className={cn(
"aspect-square size-full rounded-full object-cover",
className
)}
data-slot="avatar-image"
referrerPolicy={referrerPolicy}
src={src}
{...props}
/>
);
}
function AvatarFallback({ className, ...props }: React.ComponentProps<"span">) {
const { imageLoadingStatus } = useAvatarContext("AvatarFallback");
if (imageLoadingStatus === "loaded") {
return null;
}
return (
<span
className={cn(
"bg-muted text-muted-foreground data-[status=error]:bg-destructive flex size-full items-center justify-center rounded-full text-sm group-data-[size=sm]/avatar:text-xs data-[status=error]:text-white",
className
)}
data-slot="avatar-fallback"
data-status={imageLoadingStatus}
{...props}
/>
);
}
function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
return (
<span
className={cn(
"bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-blend-color ring-2 select-none",
"group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
"group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
"group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
className
)}
data-slot="avatar-badge"
{...props}
/>
);
}
function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"group/avatar-group *:data-[slot=avatar]:ring-background flex -space-x-2 *:data-[slot=avatar]:ring-2",
className
)}
data-slot="avatar-group"
{...props}
/>
);
}
function AvatarGroupCount({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
className={cn(
"bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 items-center justify-center rounded-full text-sm ring-2 group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
className
)}
data-slot="avatar-group-count"
{...props}
/>
);
}
export {
Avatar,
AvatarBadge,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
type AvatarImageProps,
};Copy the demo avatars into your project.
The CLI copies five AVIF avatars into public/avatars/:
female-l-1, female-l-2, female-l-3, male-l, male-r.
The -l suffix faces left, -r faces right. Use one direction
consistently within a single row or group.
Update the import paths to match your project setup.
Usage
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";<Avatar>
<AvatarImage src="/avatars/me.avif" />
<AvatarFallback>ME</AvatarFallback>
</Avatar>Pass grayscale through className to desaturate. Demo assets follow a -l (facing left) and -r (facing right) convention — pick one per row.
Group
AvatarGroup overlaps avatars with a 2px background ring between each one, keeping the stack readable. Place AvatarGroupCount as the last child to show how many more are hidden, and AvatarBadge inside an Avatar to indicate presence. Swap to right-to-left stacking with className="flex-row-reverse".
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarImage,
} from "@/components/ui/avatar";
export function AvatarGroupDemo() {
return (
<AvatarGroup aria-label="3 participants">
<Avatar>
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-3.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
</AvatarGroup>
);
}With count
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar";
export function AvatarCount() {
return (
<AvatarGroup>
<Avatar>
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-3.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/male-l.avif" />
<AvatarFallback>MX</AvatarFallback>
</Avatar>
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
);
}<AvatarGroup>
<Avatar>
<AvatarImage src="/avatars/anna.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/sara.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/liv.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>With badge
Place AvatarBadge as the last child of an Avatar. Its position is automatic (bottom-right). Put the status in sr-only text inside the badge so screen readers announce it.
import {
Avatar,
AvatarBadge,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar";
export function AvatarBadgeGroup() {
return (
<AvatarGroup>
<Avatar>
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
<AvatarBadge className="bg-green-600 dark:bg-green-800">
<span className="sr-only">Online</span>
</AvatarBadge>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
<AvatarBadge className="bg-yellow-500 dark:bg-yellow-700">
<span className="sr-only">Away</span>
</AvatarBadge>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/male-l.avif" />
<AvatarFallback>MX</AvatarFallback>
</Avatar>
<AvatarGroupCount>+5</AvatarGroupCount>
</AvatarGroup>
);
}With image and fallback
Pass src on AvatarImage. AvatarFallback renders while the image loads, when it fails, or when no image is supplied. A failed load auto-styles the fallback with the destructive token. Without AvatarImage, the fallback keeps the muted surface.
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarImage,
} from "@/components/ui/avatar";
export function AvatarImageFallback() {
return (
<div className="flex flex-row flex-wrap items-center gap-6">
<AvatarGroup>
<Avatar>
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-3.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
</AvatarGroup>
<AvatarGroup>
<Avatar>
<AvatarImage src="/avatars/missing-a.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/missing-b.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/missing-c.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
</AvatarGroup>
<AvatarGroup>
<Avatar>
<AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar>
<AvatarFallback>AI</AvatarFallback>
</Avatar>
<Avatar>
<AvatarFallback>?</AvatarFallback>
</Avatar>
</AvatarGroup>
</div>
);
}Sizes
Three sizes are available via the size prop. The default is 32px, sm is 24px, lg is 40px. Pass size on each Avatar in a group and the trailing AvatarGroupCount follows.
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar";
export function AvatarSizes() {
return (
<div className="flex flex-row flex-wrap items-center gap-6">
<AvatarGroup>
<Avatar size="sm">
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar size="sm">
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar size="sm">
<AvatarImage src="/avatars/female-l-3.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
<AvatarGroup>
<Avatar>
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="/avatars/female-l-3.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
<AvatarGroup>
<Avatar size="lg">
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>AN</AvatarFallback>
</Avatar>
<Avatar size="lg">
<AvatarImage src="/avatars/female-l-2.avif" />
<AvatarFallback>SA</AvatarFallback>
</Avatar>
<Avatar size="lg">
<AvatarImage src="/avatars/female-l-3.avif" />
<AvatarFallback>LV</AvatarFallback>
</Avatar>
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
</div>
);
}In context
Pair Avatar with Message and Bubble for a chat layout.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import {
Bubble,
BubbleContent,
Message,
MessageAvatar,
MessageContent,
MessageHeader,
} from "@/components/ui/message";
export function AvatarContext() {
return (
<div className="w-full max-w-md space-y-3 p-6">
<Message>
<MessageAvatar>
<Avatar>
<AvatarImage src="/avatars/male-r.avif" />
<AvatarFallback>R</AvatarFallback>
</Avatar>
</MessageAvatar>
<MessageContent>
<MessageHeader>Assistant</MessageHeader>
<Bubble>
<BubbleContent>Reading your build log now.</BubbleContent>
</Bubble>
</MessageContent>
</Message>
<Message align="end">
<MessageAvatar>
<Avatar>
<AvatarImage src="/avatars/female-l-1.avif" />
<AvatarFallback>ME</AvatarFallback>
</Avatar>
</MessageAvatar>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>Thanks!</BubbleContent>
</Bubble>
</MessageContent>
</Message>
</div>
);
}API Reference
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
size | smdefaultlg | default | Controls the diameter of the avatar (24px / 32px / 40px). |
AvatarImage
Renders the avatar image. Requires src and alt. Applies object-cover and rounded-full. Hidden until the image finishes loading, so the fallback shows first.
AvatarFallback
Renders children when the image is missing, still loading, or fails. Use 2–3 character initials.
AvatarBadge
Extends React.ComponentProps<"span">. Positioned absolutely at the bottom-right. Pass a background color with className (e.g., bg-green-600).
AvatarGroup / AvatarGroupCount
Extend React.ComponentProps<"div">. Group applies -space-x-2 and a 2px background ring per avatar. Count inherits the size of the group's avatars via has-data-[size=lg].
Accessibility
- Always pass
alton AvatarImage — describe the person, not the file. Use@usernamefor handles. - AvatarFallback initials act as a visual label but are not read as a name. If the avatar has semantic meaning, wrap the group in a container with
aria-label. - AvatarBadge is decorative. Convey the status in text when it matters (e.g., "Online").
- AvatarGroup should have an accessible label like
aria-label="3 participants"when it summarizes a list.
Best Practices
- Always include a fallback.
AvatarFallbackrenders when the image fails or is missing. - Size by context. 24px in lists, 40px in headers, 64px in profiles.
- Add an accessible name. Wrap in a button with
aria-labelwhen clickable. - Do not rely on the image alone. Pair with the user's name or a tooltip.