# 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>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add avatar
```

## Usage

### size

```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>
```

### variant

```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>
```

### image

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.

```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>
```

### Fallback

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

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

## Framework Availability
Avatar is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## 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.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.