Avatar Primitive
Avatar is a Starwind Runtime primitive in the static-semantic contract family.
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 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 Toggle
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 Toggle
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
- State control support
- 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.
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 Toggle
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
State
State Type Props Toggle
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
- State control support
- 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.
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 Toggle
delay number -
- Description
- Sets how long to wait before showing fallback content.
- Kind
- option
- Targets
- fallback
- Full type
- number
State
State Type Props Toggle
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
- State control support
- 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.
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
- -
Related Styled Components
Component Relationship
Avatar Direct primitive