# Avatar Primitive

Avatar is a Starwind Runtime primitive in the static-semantic contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Avatar anatomy with the Runtime wiring included.
```astro
---
import { Avatar } from "@starwind-ui/astro/avatar";
---

<Avatar.Root>
  <Avatar.Image alt="Starwind UI" src="/avatar.png" />
  <Avatar.Fallback>SW</Avatar.Fallback>
</Avatar.Root>
```

### React
Use the React primitive adapter when Avatar state participates in React rendering.
```tsx
import { Avatar } from "@starwind-ui/react/avatar";

export function Example() {
  return (
    <Avatar.Root>
      <Avatar.Image alt="Starwind UI" src="/avatar.png" />
      <Avatar.Fallback>SW</Avatar.Fallback>
    </Avatar.Root>
  );
}
```

### HTML
Render the Avatar data-sw-* contract yourself, then initialize createAvatar.
```html
<span data-sw-avatar>
  <img data-sw-avatar-image style="visibility: hidden" alt="Starwind UI" src="/avatar.png" />
  <span data-sw-avatar-fallback hidden>SW</span>
</span>

<script type="module">
  import { createAvatar } from "@starwind-ui/runtime/avatar";

  const root = document.querySelector("[data-sw-avatar]");
  if (root) {
    createAvatar(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Avatar anatomy.
```vue
<script setup lang="ts">
import Avatar from "@starwind-ui/vue/avatar";
</script>

<template>
  <Avatar.Root>
    <Avatar.Image alt="Starwind UI" src="/avatar.png" />
    <Avatar.Fallback>SW</Avatar.Fallback>
  </Avatar.Root>
</template>
```
## API Reference
### Root
The main element that owns the Avatar Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-avatar` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-avatar` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-image-loading-status` | state | - | Reflects the image loading status state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| imageLoadingStatus | `AvatarImageLoadingStatus` | - | - | `data-image-loading-status` | `getImageLoadingStatus` | `setImageLoadingStatus` | Tracks whether the Avatar image is loading, loaded, or failed. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| loadingStatusChange | onLoadingStatusChange | starwind:loading-status-change | status: `AvatarImageLoadingStatus` | AvatarLoadingStatusChangeDetails | after-state-commit | No | Fires when the image loading status changes for Avatar. | - |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar`, `data-image-loading-status` | The root needs an initial loading-status marker so image and fallback state can style before the controller attaches. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Image
The image element managed by Avatar.
| Fact | Value |
| --- | --- |
| Default element | `img` |
| Discovery hook | `data-sw-avatar-image` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| alt | `string` | - | attribute | Provides accessible alternative text for the image. | - |
| image | `ImageMetadata` | - | rendering | Provides image loading state to the avatar image part. | - |
| src | `string` | - | attribute | Sets the image source. | - |
| onLoadingStatusChange | `(status: AvatarImageLoadingStatus, details: AvatarLoadingStatusChangeDetails) => void` | - | callback | Runs when on loading status change changes for Avatar. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-avatar-image` | runtime | - | Marks the Image part so Starwind Runtime can find it. |
| `data-image-loading-status` | state | - | Reflects the image loading status state on the Image part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| imageLoadingStatus | `AvatarImageLoadingStatus` | - | - | `data-image-loading-status` | `getImageLoadingStatus` | `setImageLoadingStatus` | Tracks whether the Avatar image is loading, loaded, or failed. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| image | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar-image`, `data-image-loading-status` | Images start visibility-hidden so they retain a layout box and remain eligible for native lazy loading until the Runtime confirms they loaded. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |

### Fallback
Fallback content shown when Avatar cannot load.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-avatar-fallback` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| delay | `number` | - | option | Sets how long to wait before showing fallback content. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-avatar-fallback` | runtime | - | Marks the Fallback part so Starwind Runtime can find it. |
| `data-delay` | prop | - | Reflects the delay prop on the Fallback part. |
| `data-image-loading-status` | state | - | Reflects the image loading status state on the Fallback part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| imageLoadingStatus | `AvatarImageLoadingStatus` | - | - | `data-image-loading-status` | `getImageLoadingStatus` | `setImageLoadingStatus` | Tracks whether the Avatar image is loading, loaded, or failed. | **React:** The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.<br>**Astro:** listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.<br>**Runtime / HTML:** Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates. |
#### Refs
| Part | Public |
| --- | --- |
| fallback | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar-fallback`, `data-delay`, `data-image-loading-status` | Fallbacks carry optional delay metadata and may start hidden while the timer runs. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createAvatar`](/docs/runtime/#create-avatar) |
| Import | `@starwind-ui/runtime/avatar` |
| Root part | root |
| Option props | - |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Avatar](/docs/components/avatar/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/avatar` | `createAvatar` |
| Astro Primitive | `@starwind-ui/astro/avatar` | `Avatar`, `AvatarRoot`, `AvatarImage`, `AvatarFallback` |
| React Primitive | `@starwind-ui/react/avatar` | `Avatar`, `AvatarRoot`, `AvatarImage`, `AvatarFallback` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Avatar` |
| runtime-factory | `createAvatar` |
| part | `Avatar.Root` |
| part | `Avatar.Image` |
| part | `Avatar.Fallback` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.1
- Kept images eligible for native lazy loading while the Runtime conceals their loading and error states, including Astro images rendered from imported assets.
### v0.1.0
- Introduced image loading state, delayed fallback behavior, and accessible image status coordination.