Avatar

Introduction

The Avatar component provides a versatile way to display user or entity representations. It supports images, initials, and fallback icons with customizable sizes, shapes, and color schemes. The component is designed to be accessible and adapts to both light and dark modes automatically.

AvatarGroup

The Avatar component can be used individually or within an AvatarGroup component to display multiple avatars in either a condensed overlapping layout or a grid layout.

When to use

Use the Avatar component when you need to:

• Display user profile pictures
• Show team members or contributors
• Represent entities in a visual way
• Create user directories or listings
• Show authors of content
• Indicate participants in discussions
• Display account information

Quick example

JD

JD

JS

RJ

AL

MT

The Avatar component handles different content types and provides options for accessible fallbacks.

Usage

Learn how to implement the Avatar component in your project, from basic usage to advanced configurations.

Basic

---
import { Avatar } from 'accessible-astro-components'
---

<!-- With image -->
<Avatar
  img="https://example.com/profile.jpg"
  label="User profile"
/>

<!-- With initials -->
<Avatar
  initials="JD"
  label="John Doe"
/>

<!-- Default fallback icon -->
<Avatar
  label="Unknown user"
/>

Sizes

<Avatar
  initials="SM"
  size="sm"
  label="Small avatar"
/>

<Avatar
  initials="MD"
  size="md"
  label="Medium avatar"
/>

<Avatar
  initials="LG"
  size="lg"
  label="Large avatar"
/>

<!-- Custom size -->
<Avatar
  initials="CS"
  size="10rem"
  label="Custom size avatar"
/>

Types and shapes

<!-- Different types (color schemes) -->
<Avatar initials="DF" type="default" label="Default type" />
<Avatar initials="IN" type="info" label="Info type" />
<Avatar initials="SU" type="success" label="Success type" />
<Avatar initials="WA" type="warning" label="Warning type" />
<Avatar initials="ER" type="error" label="Error type" />

<!-- Square shape -->
<Avatar
  initials="SQ"
  shape="square"
  label="Square avatar"
/>

With text content

<Avatar
  img="https://example.com/profile.jpg"
  title="Jane Smith"
  subtitle="Product Designer"
/>

<Avatar
  initials="JS"
  title="Jane Smith"
  subtitle="Product Designer"
/>

Accessibility

When using the Avatar component without a title, always provide a label prop for screen readers. When a title is provided, the label prop becomes optional.

Avatar groups

---
import { Avatar, AvatarGroup } from 'accessible-astro-components'
---

<!-- Condensed group (overlapping) -->
<AvatarGroup overlapAmount="-1rem">
  <Avatar initials="JD" label="John Doe" />
  <Avatar initials="JS" label="Jane Smith" />
  <Avatar initials="RJ" label="Robert Johnson" />
</AvatarGroup>

<!-- Grid layout -->
<AvatarGroup
  display="grid"
  gridItemsSize="200px"
  gridGap="1rem"
>
  <Avatar
    img="https://example.com/user1.jpg"
    title="John Doe"
    subtitle="Developer"
  />
  <Avatar
    img="https://example.com/user2.jpg"
    title="Jane Smith"
    subtitle="Designer"
  />
  <Avatar
    initials="RJ"
    title="Robert Johnson"
    subtitle="Manager"
  />
</AvatarGroup>

Props

Avatar Props

Configure the Avatar component using these available props to customize its behavior and appearance.

Prop	Type	Default	Description
img	string	-	Image source URL for the avatar
initials	string	-	Initials to display when no image is available
type	'default' | 'info' | 'success' | 'warning' | 'error'	'default'	Type/color variant of the avatar
shape	'round' | 'square'	'round'	Shape of the avatar
size	'sm' | 'md' | 'lg' | string	'md'	Size of the avatar (predefined or custom value)
title	string	-	Primary text to display next to the avatar
subtitle	string	-	Secondary text to display next to the avatar
label	string	-	Accessible label for screen readers (required when no title is provided)
class	string	''	Additional CSS classes to apply

AvatarGroup Props

Configure the AvatarGroup component to control how multiple avatars are displayed.

Prop	Type	Default	Description
display	'condensed' | 'grid'	'condensed'	Display mode for the avatar group
gridItemsSize	string	'250px'	Size of the grid items (used for grid display mode)
gridGap	string	'1rem'	Gap between grid items (used for grid display mode)
overlapAmount	string	'-1rem'	Overlap amount for condensed mode (negative margin)
class	string	''	Additional CSS classes to apply

Accessibility

Accessibility isn’t an afterthought - it’s built into the core of this component through semantic HTML elements and proper ARIA attributes. The Avatar component is built with accessibility in mind:

• Requires an accessible label via label prop or title prop
• Uses empty alt attributes for decorative images
• Provides fallback content when images fail to load
• High contrast color combinations
• Automatic light/dark mode adaptation
• Semantic HTML structure

Image avatars

When using images in avatars, the component sets an empty alt attribute since the image is considered decorative. The accessible name comes from either the label prop or the title prop.

Styling

Make the Avatar component your own with custom styling while maintaining its accessibility features.

Accessibility considerations

When applying custom styles, ensure you maintain sufficient color contrast ratios for text content and initials.

Custom CSS

/* Option 1: Using :global() in your style block */
<style>
  :global(.avatar .initials-container) {
    border-width: 3px;
    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  }

  :global(.avatar .title) {
    font-weight: 700;
  }

  :global(.avatar .subtitle) {
    font-style: italic;
  }
</style>

/* Option 2: Using is:global on the style tag */
<style is:global>
  .avatar .initials-container {
    border-width: 3px;
    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  }

  .avatar .title {
    font-weight: 700;
  }

  .avatar .subtitle {
    font-style: italic;
  }
</style>

Tailwind Classes

<Avatar
  class="shadow-md hover:shadow-lg transition-shadow duration-300"
  initials="JD"
  label="John Doe"
/>

Style scoping

Astro components use scoped styles by default. To override component styles, you’ll need to use either :global() selectors or the is:global directive on your style tag.

Interactive examples

See the Avatar component in action with these practical examples demonstrating different variants and styling options.

Image avatars with text

John Doe

Astro Developer

Jane Smith

Astro Designer

William Johnson

Astro Manager

Initials with different types

DF

IN

SU

WA

ER

Square avatars

MT

Avatar groups

Condensed group

JD

JS

RJ

AL

MT

Grid layout

JD

Jane

Designer

JD

John

Developer

SM

Sarah

Manager

MT

Mike

Tester