# Avatar
URL: /design/components/avatar

People as initials or images, alone or stacked in groups.

> For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths.

\[interactive preview component AvatarSpecimen omitted]

Code for AvatarSpecimen preview:

```tsx
"use client";

import { useState, type ReactNode } from "react";
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
} from "@/components/ui/avatar";

function AvatarSpecimen(): ReactNode {
  return (
    <Avatar>
      <AvatarFallback>AU</AvatarFallback>
    </Avatar>
    <AvatarGroup>
      <Avatar>
        <AvatarFallback>TL</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>MK</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>JS</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}
```

## Installation

Install the dependencies:

- packages

  - @base-ui/react

Copy the source into `components/ui/avatar.tsx`. Registry items that depend on it install it automatically.

- code

  "use client"; import \* as React from "react"; import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"; import { cn } from "@/lib/utils"; function Avatar({ className, size = "default", ...props }: AvatarPrimitive.Root.Props & { size?: "default" | "sm" | "lg"; }) { return ( \<AvatarPrimitive.Root data-slot="avatar" data-size={size} 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, )} {...props} /> ); } function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) { return ( \<AvatarPrimitive.Image data-slot="avatar-image" className={cn( "aspect-square size-full rounded-full object-cover", className, )} {...props} /> ); } function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props) { return ( \<AvatarPrimitive.Fallback data-slot="avatar-fallback" className={cn( "bg-muted text-muted-foreground flex size-full items-center justify-center rounded-full text-sm group-data-\[size=sm]/avatar:text-xs", className, )} {...props} /> ); } function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) { return ( \<span data-slot="avatar-badge" 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, )} {...props} /> ); } function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) { return ( \<div data-slot="avatar-group" className={cn( "group/avatar-group \*:data-\[slot=avatar]:ring-background flex -space-x-2 \*:data-\[slot=avatar]:ring-2", className, )} {...props} /> ); } function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">) { return ( \<div data-slot="avatar-group-count" 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, )} {...props} /> ); } export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge, };

* title

  components/ui/avatar.tsx

* copyText

  "use client"; import \* as React from "react"; import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"; import { cn } from "@/lib/utils"; function Avatar({ className, size = "default", ...props }: AvatarPrimitive.Root.Props & { size?: "default" | "sm" | "lg"; }) { return ( \<AvatarPrimitive.Root data-slot="avatar" data-size={size} 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, )} {...props} /> ); } function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) { return ( \<AvatarPrimitive.Image data-slot="avatar-image" className={cn( "aspect-square size-full rounded-full object-cover", className, )} {...props} /> ); } function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props) { return ( \<AvatarPrimitive.Fallback data-slot="avatar-fallback" className={cn( "bg-muted text-muted-foreground flex size-full items-center justify-center rounded-full text-sm group-data-\[size=sm]/avatar:text-xs", className, )} {...props} /> ); } function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) { return ( \<span data-slot="avatar-badge" 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, )} {...props} /> ); } function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) { return ( \<div data-slot="avatar-group" className={cn( "group/avatar-group \*:data-\[slot=avatar]:ring-background flex -space-x-2 \*:data-\[slot=avatar]:ring-2", className, )} {...props} /> ); } function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">) { return ( \<div data-slot="avatar-group-count" 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, )} {...props} /> ); } export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge, };

* viewportClassName

  max-h-\[450px]

- language

  tsx

- code

  "use client"; import \* as React from "react"; import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"; import { cn } from "@/lib/utils"; function Avatar({ className, size = "default", ...props }: AvatarPrimitive.Root.Props & { size?: "default" | "sm" | "lg"; }) { return ( \<AvatarPrimitive.Root data-slot="avatar" data-size={size} 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, )} {...props} /> ); } function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) { return ( \<AvatarPrimitive.Image data-slot="avatar-image" className={cn( "aspect-square size-full rounded-full object-cover", className, )} {...props} /> ); } function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props) { return ( \<AvatarPrimitive.Fallback data-slot="avatar-fallback" className={cn( "bg-muted text-muted-foreground flex size-full items-center justify-center rounded-full text-sm group-data-\[size=sm]/avatar:text-xs", className, )} {...props} /> ); } function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) { return ( \<span data-slot="avatar-badge" 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, )} {...props} /> ); } function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) { return ( \<div data-slot="avatar-group" className={cn( "group/avatar-group \*:data-\[slot=avatar]:ring-background flex -space-x-2 \*:data-\[slot=avatar]:ring-2", className, )} {...props} /> ); } function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">) { return ( \<div data-slot="avatar-group-count" 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, )} {...props} /> ); } export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge, };

## Usage

```
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="/avatar.png" alt="Ada" />
      <AvatarFallback>AD</AvatarFallback>
    </Avatar>
  );
}
```

## Examples

### Sizes

\[interactive preview component AvatarSizesSpecimen omitted]

Code for AvatarSizesSpecimen preview:

```tsx
"use client";

import { useState, type ReactNode } from "react";
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
} from "@/components/ui/avatar";

function AvatarSizesSpecimen(): ReactNode {
  return (
    <Avatar size="sm">
      <AvatarFallback>SM</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>MD</AvatarFallback>
    </Avatar>
    <Avatar size="lg">
      <AvatarFallback>LG</AvatarFallback>
    </Avatar>
  );
}
```

### Status badge

`AvatarBadge` pins a marker to the rim; give it a background to carry the status.

\[interactive preview component AvatarBadgeSpecimen omitted]

Code for AvatarBadgeSpecimen preview:

```tsx
"use client";

import { useState, type ReactNode } from "react";
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
} from "@/components/ui/avatar";

function AvatarBadgeSpecimen(): ReactNode {
  return (
    <Avatar>
      <AvatarFallback>ON</AvatarFallback>
      <AvatarBadge className="bg-emerald-500" />
    </Avatar>
    <Avatar>
      <AvatarFallback>AW</AvatarFallback>
      <AvatarBadge className="bg-amber-500" />
    </Avatar>
  );
}
```

## API Reference

### Avatar

Wraps Base UI's Avatar root.

- `size`: `"sm" | "default" | "lg"` (default `"default"`) — 24, 32, or 40 pixels.

### Parts

| Part               | Description                                     |
| ------------------ | ----------------------------------------------- |
| `AvatarImage`      | The image, shown once it loads.                 |
| `AvatarFallback`   | Initials or an icon while the image is missing. |
| `AvatarBadge`      | A status marker pinned to the rim.              |
| `AvatarGroup`      | Overlapping stack of avatars.                   |
| `AvatarGroupCount` | Overflow count that closes a group.             |