# Avatar Primitive

Avatar is a Starwind Runtime primitive in the static-semantic contract family.
## 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 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>
```
## 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 coordinates this state through the primitive adapter instead of a dedicated state prop. Runtime/HTML reads initial state from data-image-loading-status and updates with setImageLoadingStatus. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| 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. |
#### 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 coordinates this state through the primitive adapter instead of a dedicated state prop. Runtime/HTML reads initial state from data-image-loading-status and updates with setImageLoadingStatus. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Refs
| Part | Public |
| --- | --- |
| image | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-avatar-image`, `data-image-loading-status` | Images start hidden until the runtime confirms the native image has 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 |
| --- | --- | --- | --- | --- |
| 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 coordinates this state through the primitive adapter instead of a dedicated state prop. Runtime/HTML reads initial state from data-image-loading-status and updates with setImageLoadingStatus. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### 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` |