---
url: https://docs.tailor.tech/app-shell/components/avatar.md
description: User avatar with image and fallback (Base UI)
---

# Avatar

The `Avatar` component wraps Base UI Avatar: a root container with an optional image and fallback content (typically initials) when the image is missing or fails to load.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/avatar)

## Import

```tsx
import { Avatar } from "@tailor-platform/app-shell";
```

## Basic usage

```tsx
<Avatar.Root>
  <Avatar.Image src="/user.png" alt="Jane Doe" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
```

## Parts

| Part              | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `Avatar.Root`     | Outer container; applies size and surface styles.          |
| `Avatar.Image`    | `<img>` for the photo; hidden when not loaded or on error. |
| `Avatar.Fallback` | Shown when there is no image or the image failed to load.  |

## Root props

| Prop        | Type                                | Default     | Description                |
| ----------- | ----------------------------------- | ----------- | -------------------------- |
| `size`      | `"xs" \| "sm" \| "default" \| "lg"` | `"default"` | Circle size (28px default) |
| `className` | `string`                            | —           | Extra classes              |
| `children`  | `React.ReactNode`                   | —           | Image + fallback           |

`Avatar.Root` forwards other stable props from Base UI (for example `aria-hidden`, `style`) and standard HTML attributes for the `<span>` root.

## Sizes

The smallest size, `xs` (16px), is intended for compact/inline contexts and single-glyph or icon content; two-letter initials will be cramped.

```tsx
<Avatar.Root size="xs">
  <Avatar.Fallback>A</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="sm">
  <Avatar.Fallback>AB</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="default">
  <Avatar.Fallback>CD</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="lg">
  <Avatar.Fallback>EF</Avatar.Fallback>
</Avatar.Root>
```

## Types

`AvatarProps` is the props type for `Avatar.Root` (includes `size` and Base UI root props). Import when wrapping or composing:

```tsx
import { Avatar, type AvatarProps } from "@tailor-platform/app-shell";
```

## `avatarVariants`

The same size styles used by `Avatar.Root` are exported as `avatarVariants` (for example if you need to mirror avatar dimensions in layout code). Prefer the `size` prop on `Avatar.Root` for normal use.