Avatar

Display user profile images with fallback support and status indicators

Primitive

An avatar shows a user's profile image, falling back to initials or an icon when the image is missing or fails to load. Use it in comment threads, member lists, navbars, and anywhere you identify a person or account.

Preview

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"
 
export default function AvatarBasic() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />

Installation

npxnpx shadcn@latest add @cubby-ui/avatar

Usage


import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"


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

Composition

Avatar
├── AvatarImage
└── AvatarFallback

Examples

Sizes

Use size to set the avatar's dimensions.

SMMDLGXL

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"
 
export default function AvatarSizes() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="sm">

Size	Description
`sm`	A compact avatar.
`md`	The default avatar.
`lg`	A larger avatar.

Fallback

AvatarFallback renders when the image is missing or fails to load.

JDABTK

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"
 
export default function AvatarFallbackDemo() {
  return (
    <div className="flex items-center gap-4">
      <Avatar>

Avatar Group

Overlap avatars to show a group of users compactly.

CNVCLN+5

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"
 
export default function AvatarGroup() {
  return (
    <div className="flex -space-x-2">
      <Avatar className="border-2 border-background">

With Status Indicator

Overlay a dot on the avatar to show online or offline state.

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"
 
export default function AvatarWithStatusIndicator() {
  return (
    <div className="flex items-center gap-4">
      <div className="relative">

Lazy and Optimized Images

By default, AvatarImage preloads src in the background and shows the image once it has loaded. Add keepMounted to render the image element right away and let it load in place instead. This lets loading="lazy" defer offscreen avatars, and works with image optimizers like next/image, which request a different URL than the raw src. The fallback shows until the image loads, and stays if it fails.

CNVCLNMS

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/cubby-ui/avatar"
 
const people = [
  { name: "shadcn", initials: "CN", src: "https://github.com/shadcn.png" },
  { name: "Vercel", initials: "VC", src: "https://github.com/vercel.png" },
  { name: "Linear", initials: "LN", src: "https://github.com/linear.png" },


import Image from "next/image";
 
<Avatar>
  <AvatarImage
    keepMounted
    render={<Image src="/users/ada.jpg" width={40} height={40} alt="Ada Lovelace" />}
  />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>

Accessibility

Give AvatarImage an alt describing who it represents (typically the person's name). Provide an AvatarFallback so the avatar still conveys identity when the image fails to load.


<Avatar>
  <AvatarImage src="/users/ada.jpg" alt="Ada Lovelace" />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>

Avatar

Preview

Installation

Usage

Composition

Examples

Sizes

Fallback

Avatar Group

With Status Indicator

Lazy and Optimized Images

Accessibility

API Reference

Custom Props

Avatar