Design System Beacon

Avatar

User avatars for displaying profile pictures, initials, or icons. Use avatars to represent users, teams, or entities.

Overview

Avatars are visual representations of users or entities. The Avatar component supports multiple content types, sizes, shapes, and color variants to fit different contexts and use cases.

All avatar styles are built using design tokens, ensuring consistency across themes and hues. Use the interactive playground below to explore all available combinations.

Interactive Playground

Use the controls to customize the avatar and see how it looks in real-time. Toggle between themes and hues to see how avatars adapt to different contexts.

Type

Color

Variant

Color

Size

Round

Stroke

<Avatar />

Anatomy

An avatar consists of a container that holds the content (icon, text, or image).

Containerwidth, height, border-radius

Contenticon, text, or image

Background--bg-*-solid or --bg-*-tonal

Variants & States

Avatars come in different shapes, sizes, content types, and color variants to fit various use cases.

Icon

Use icons for generic user representation or when no specific user data is available.

Text

Use initials or short text when you want to display user names without images.

Image

Use profile images for personalized user representation. Includes fallback handling.

Round & Stroke

Default corner radius is 8px. Toggle to make fully round or add stroke border.

For a complete matrix of all avatar variants, sizes, and colors, see the Avatar component in Figma.

Usage Guidelines

Use avatars to represent users, team members, or entities.
Use appropriate sizes based on context and importance.
Provide meaningful initials (2 characters) for text avatars.
Use images when available for better personalization.
Ensure sufficient color contrast for accessibility.
Use consistent avatar styles throughout your application.

Don't

Don't use avatars for decorative purposes only.
Don't use more than 2 characters for text avatars.
Don't use low-quality or inappropriate images.
Don't mix avatar shapes inconsistently in the same context.
Don't use avatars that are too small to recognize.
Don't forget to provide alt text for image avatars.

Accessibility

Provide descriptive alt text for image avatars using the alt attribute.
Ensure sufficient color contrast between background and content.
Use meaningful initials that help identify the user.
Consider using ARIA labels when avatars are interactive.
Ensure avatars are large enough to be recognizable (minimum 32px).

API Reference

Avatar component props and types.

AvatarProps

interface AvatarProps {
  size?: "sm" | "md" | "lg" | "xl";
  type?: "icon" | "text" | "image";
  color?: "primary" | "neutral" | "success" | "critical" | "warning";
  variant?: "solid" | "faded";
  isRound?: boolean;
  hasStroke?: boolean;
  initials?: string;
  imageUrl?: string;
  icon?: ComponentType<IconProps>;
  alt?: string;
}

Props

size

"sm" | "md" | "lg" | "xl"

"md"

Avatar container size: sm (32px), md (48px), lg (64px), xl (124px). Note: xl only available for image type.

type

"icon" | "text" | "image"

"icon"

Content type displayed in avatar. Icon sizes: sm=16px, md=24px, lg=40px. Text sizes: sm=--fonts-body-small-text-size, md=--fonts-body-regular-text-size, lg=h5. Extra large only available for image type.

color

"primary" | "neutral" | "success" | "critical" | "warning"

"primary"

Background color theme

variant

"solid" | "faded"

"solid"

Color variant: solid (full color) or faded (tonal)

isRound

boolean

false

Make avatar fully round (50% border-radius). Default is 8px corner radius.

hasStroke

boolean

false

Add stroke border to avatar

initials

string

"JD"

Text to display for text type avatars (max 2 characters)

imageUrl

string

—

Image URL for image type avatars

icon

ComponentType<IconProps>

—

Custom icon component for icon type avatars. Defaults to UserPersonIcon if not provided.

alt

string

—

Alt text for image avatars (accessibility)

Usage Examples

Copyable code snippets for common avatar use cases.

Basic Avatar

import { Avatar } from 'beacon-ui';

<Avatar />

Custom Icon

import { Avatar } from 'beacon-ui';
import { UserCircleIcon, SettingsGearIcon } from '@/components/icons';

<Avatar type="icon" icon={UserCircleIcon} />
<Avatar type="icon" icon={SettingsGearIcon} color="success" />

Text Avatar

import { Avatar } from 'beacon-ui';

<Avatar type="text" initials="JD" />

Image Avatar

import { Avatar } from 'beacon-ui';

<Avatar 
  type="image"
  imageUrl="/images/avatars/avatar-female.png"
  alt="User avatar"
/>

Sizes

import { Avatar } from 'beacon-ui';

<Avatar size="sm" />
<Avatar size="md" />
<Avatar size="lg" />
<Avatar size="xl" />

Round & Stroke

import { Avatar } from 'beacon-ui';

<Avatar />
<Avatar isRound />
<Avatar hasStroke />
<Avatar isRound hasStroke />

Colors & Variants

import { Avatar } from 'beacon-ui';

<Avatar color="primary" variant="solid" />
<Avatar color="success" variant="faded" />
<Avatar color="neutral" variant="solid" />