# Avatar

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
---
<Avatar>
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
      <AvatarFallback>JD</AvatarFallback>
    </Avatar>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
</script>

<template>
  <Avatar>
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add avatar --framework astro
```
</DocsTabsContent>
```bash
npx starwind@latest add avatar --framework react
```
</DocsTabsContent>
```bash
npx starwind@latest add avatar --framework vue
```
</DocsTabsContent>
</DocsTabs>

## Usage

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
---
<Avatar>
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
      <AvatarFallback>JD</AvatarFallback>
    </Avatar>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
</script>

<template>
  <Avatar>
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Composition

Use this structure so the fallback appears when the image cannot load:

```text
Avatar
├── AvatarImage
└── AvatarFallback
```

## Sizes

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
---
<Avatar size="sm">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar size="md">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar size="lg">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <>
      <Avatar size="sm">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar size="md">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
</script>

<template>
  <Avatar size="sm">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar size="md">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar size="lg">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Variants

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
---
<Avatar variant="default">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar variant="primary">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar variant="secondary">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar variant="info">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar variant="success">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar variant="warning">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar variant="error">
  <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <>
      <Avatar variant="default">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar variant="primary">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar variant="secondary">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar variant="info">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar variant="success">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar variant="warning">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar variant="error">
        <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
</script>

<template>
  <Avatar variant="default">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar variant="primary">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar variant="secondary">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar variant="info">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar variant="success">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar variant="warning">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar variant="error">
    <AvatarImage src="https://i.pravatar.cc/150?u=a04258a2462d826712d" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Images

Rather than passing an image URL, you can also pass an imported image to the `AvatarImage` component. This will optimize the image using the astro:assets `<Image/>` component.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import GigaChad from "@/assets/images/giga-chad.jpg";
---
<Avatar>
  <AvatarImage image={GigaChad} alt="GC" />
  <AvatarFallback>GC</AvatarFallback>
</Avatar>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import GigaChad from "@/assets/images/giga-chad.jpg";

export function Example() {
  return (
    <>
      <Avatar>
        <AvatarImage src={GigaChad} alt="GC" />
        <AvatarFallback>GC</AvatarFallback>
      </Avatar>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

const GigaChad =
  "https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=200&h=200&fit=crop";
</script>

<template>
  <Avatar>
    <AvatarImage :src="GigaChad" alt="GC" />
    <AvatarFallback>GC</AvatarFallback>
  </Avatar>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Fallback

When an image fails to load or isn't provided, the fallback content will be displayed.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
---
<Avatar>
  <AvatarImage src="invalid-url.png" alt="Branden" />
  <AvatarFallback>WR</AvatarFallback>
</Avatar>
```
  </div>
  <div slot="react">
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <>
      <Avatar>
        <AvatarImage src="invalid-url.png" alt="Branden" />
        <AvatarFallback>WR</AvatarFallback>
      </Avatar>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
</script>

<template>
  <Avatar>
    <AvatarImage src="invalid-url.png" alt="Branden" />
    <AvatarFallback>WR</AvatarFallback>
  </Avatar>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Avatar
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `variant` | `"default" \| "primary" \| "secondary" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits span attributes.

### AvatarImage
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `alt` | `string` | Yes | - | Wrapper prop | Provides alternative text for the rendered image. |
| `image` | `ImageMetadata` | No | - | Wrapper prop | Provides Astro image metadata for optimized image rendering. |
| `src` | `string` | No | - | Wrapper prop | Provides the media source URL. |
- Inherits img attributes. Omits `children`.

### AvatarFallback
- Inherits span attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Avatar Primitive](/docs/primitives/avatar/)
- Runtime factory: [`createAvatar`](/docs/runtime/#create-avatar) from `@starwind-ui/runtime/avatar`

## Changelog

### v2.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v2.0.1

- Rendered Avatar roots as inline flex containers so the small, medium, and large size variants produce exact circles while preserving image-loading and fallback visibility.

### v2.0.0

- Rebuilt Avatar on Starwind Runtime for image loading and fallback state.
- See the [Avatar Primitive](/docs/primitives/avatar/) for the underlying unstyled anatomy and behavior API.

### v1.2.3

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.2.1

- Add the ability to pass additional attributes to components

### v1.2.0

- Add a `data-slot` attribute to all components to enable global styling updates

### v1.1.1

- Adjust component to use type `VariantProps` from `tailwind-variants`. This provides greater type safety and cleans up component frontmatter.
- Add eslint disable comment for using the "onerror" function which allows us to handle an image that doesn't load. This allows us to display the fallback content.

### v1.1.0

- `tailwind-variants` now implemented. This uses `tailwind-merge` under the hood to merge Tailwind classes without style conflicts, allowing you to override any existing classes using the "class" prop.