On this page

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

Use the Astro primitive adapter to render Avatar anatomy with the Runtime wiring included.

---
import { Avatar } from "@starwind-ui/astro/avatar";
---

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

Use the React primitive adapter when Avatar state participates in React rendering.

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>
  );
}

Render the Avatar data-sw-* contract yourself, then initialize createAvatar.

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

API Reference

Root

The main element that owns the Avatar Runtime instance.

Default element: span
Discovery hook: data-sw-avatar
Role: -

Events

Event Callback Value

loadingStatusChange onLoadingStatusChange status: AvatarImageLoadingStatus

Description: Fires when the image loading status changes for Avatar.
DOM event: starwind:loading-status-change
Details type: AvatarLoadingStatusChangeDetails
Timing: after-state-commit
Cancelable: No

State

State Type Props

imageLoadingStatus AvatarImageLoadingStatus -

Description

Tracks whether the Avatar image is loading, loaded, or failed.

Initial attribute

data-image-loading-status

Runtime getter

getImageLoadingStatus

Runtime setter

setImageLoadingStatus

React

The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.

onLoadingStatusChange

Astro

listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.

starwind:loading-status-change
setImageLoadingStatus

Runtime / HTML

Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates.

data-image-loading-status
starwind:loading-status-change
setImageLoadingStatus

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-avatar - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-image-loading-status - Reflects the image loading status state on the Root part.

Image

The image element managed by Avatar.

Default element: img
Discovery hook: data-sw-avatar-image
Role: -

Props

Prop Type Default

alt string -

Description: Provides accessible alternative text for the image.
Kind: attribute
Targets: image
Full type: string

image ImageMetadata -

Description: Provides image loading state to the avatar image part.
Kind: rendering
Targets: image
Full type: ImageMetadata

src string -

Description: Sets the image source.
Kind: attribute
Targets: image
Full type: string

onLoadingStatusChange (status: AvatarImageLoadingStatus, details: AvatarLoadingStatusChangeDetails) => void -

Description

Runs when on loading status change changes for Avatar.

Kind

callback

Targets

image

Full type

(status: AvatarImageLoadingStatus, details: AvatarLoadingStatusChangeDetails) => void

React

The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.

onLoadingStatusChange

Astro

listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.

starwind:loading-status-change
setImageLoadingStatus

Runtime / HTML

Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates.

data-image-loading-status
starwind:loading-status-change
setImageLoadingStatus

State

State Type Props

imageLoadingStatus AvatarImageLoadingStatus -

Description

Tracks whether the Avatar image is loading, loaded, or failed.

Initial attribute

data-image-loading-status

Runtime getter

getImageLoadingStatus

Runtime setter

setImageLoadingStatus

React

The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.

onLoadingStatusChange

Astro

listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.

starwind:loading-status-change
setImageLoadingStatus

Runtime / HTML

Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates.

data-image-loading-status
starwind:loading-status-change
setImageLoadingStatus

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-avatar-image - Marks the Image part so Starwind Runtime can find it.

State

Attribute Value Description

data-image-loading-status - Reflects the image loading status state on the Image part.

Fallback

Fallback content shown when Avatar cannot load.

Default element: span
Discovery hook: data-sw-avatar-fallback
Role: -

Props

Prop Type Default

delay number -

Description: Sets how long to wait before showing fallback content.
Kind: option
Targets: fallback
Full type: number

State

State Type Props

imageLoadingStatus AvatarImageLoadingStatus -

Description

Tracks whether the Avatar image is loading, loaded, or failed.

Initial attribute

data-image-loading-status

Runtime getter

getImageLoadingStatus

Runtime setter

setImageLoadingStatus

React

The adapter coordinates this state without a dedicated state prop, and onLoadingStatusChange for state changes.

onLoadingStatusChange

Astro

listen for starwind:loading-status-change and call setImageLoadingStatus for later updates.

starwind:loading-status-change
setImageLoadingStatus

Runtime / HTML

Use data-image-loading-status for initial state, listen for starwind:loading-status-change, and call setImageLoadingStatus for later updates.

data-image-loading-status
starwind:loading-status-change
setImageLoadingStatus

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-avatar-fallback - Marks the Fallback part so Starwind Runtime can find it.

State

Attribute Value Description

data-image-loading-status - Reflects the image loading status state on the Fallback part.

Metadata

Attribute Value Description

data-delay - Reflects the delay prop on the Fallback part.

Runtime API

Factory: createAvatar
Import: @starwind-ui/runtime/avatar
Root hook: root data-sw-avatar
Option props: -

Component Relationship

Avatar Direct primitive

Changelog

View version history v1.0.0 4 releases

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.

Avatar Primitive

Anatomy

API Reference

Root

Events

State

Data Attributes

Runtime hooks

State

Image

Props

State

Data Attributes

Runtime hooks

State

Fallback

Props

State

Data Attributes

Runtime hooks

State

Metadata

Runtime API

Related Styled Components

Changelog

v1.0.0

v0.1.2

v0.1.1

v0.1.0