---
title: "Avatar"
description: "A circular user avatar with image support and initials fallback in three sizes."
---

An image, or the initials that stand in for one. Three sizes, all circles, all sized in the same steps the rest of the library uses.

_Live example of Avatar — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add avatar
```

npm dependencies: class-variance-authority.

Files written — React: components/ui/avatar.tsx. Vue: components/ui/avatar/Avatar.vue, components/ui/avatar/AvatarImage.vue, components/ui/avatar/AvatarFallback.vue, components/ui/avatar/index.ts.

## Usage

React:

```tsx
import { Avatar } from "@/components/ui/avatar"
```

Vue:

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

## API reference

**`Avatar`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | 24px, 40px or 80px. |
| `src` | `string` | — | Image URL. Falls back to the children when it fails to load. |
| `alt` | `string` | — | Accessible name for the image. |

Every part also accepts the native attributes of the element it renders, and a `className` that is merged rather than replaced.

## Accessibility

An avatar next to a name is decorative: the name is the accessible name, so `alt=""` is correct and repeating it is noise. An avatar that stands alone — a stack of participants, an author with no byline — needs a real `alt`.

## Tokens

Avatar reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.