On this page

Avatar

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

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

Installation

pnpx starwind@latest add avatar

npx starwind@latest add avatar

yarn dlx starwind@latest add avatar

Usage

size

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

import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <>
      <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

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

import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <>
      <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.

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

import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";
import GigaChad from "@/assets/images/giga-chad.jpg";

export function Example() {
  return (
    <>
      <Avatar>
        <AvatarImage src={GigaChad} alt="GC" />
        <AvatarFallback>GC</AvatarFallback>
      </Avatar>
    </>
  );
}

Fallback

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

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

import { Avatar, AvatarImage, AvatarFallback } from "@/components/starwind/avatar";

export function Example() {
  return (
    <>
      <Avatar>
        <AvatarImage src="invalid-url.png" alt="Branden" />
        <AvatarFallback>WR</AvatarFallback>
      </Avatar>
    </>
  );
}

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Avatar

Inherits span attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Description: Selects the component's visual variant.
Classification: Styled variant

Avatar Image

Inherits img attributes. Omits `children`.

Contains the following additional props:

Prop Type Default

alt Required string —

Description: Provides alternative text for the rendered image.
Classification: Wrapper prop

image ImageMetadata —

Description: Provides Astro image metadata for optimized image rendering.
Classification: Wrapper prop

src string —

Description: Provides the media source URL.
Classification: Wrapper prop

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Avatar.

Primitive API

Avatar Primitive

Runtime API

Avatar primitive: createAvatar from @starwind-ui/runtime/avatar

Changelog

v2.0.2

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v2.0.1

Rendered Avatar roots as inline flex containers so the small, medium, and large size variants produce exact circles while preserving image-loading and fallback visibility.

v2.0.0

Rebuilt Avatar on Starwind Runtime for image loading and fallback state.
See the Avatar Primitive 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.