The Avatar component displays an image representing a user or entity. It supports images, icons, or initials as fallback content when an image isn’t available or fails to load.

Anatomy

Usage

Basic Example

Show code

React

import { PlusAvatar } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusAvatar image="https://i.pravatar.cc/50" alt="User Name">
      </PlusAvatar>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-avatar image="https://i.pravatar.cc/50" alt="User Name">
    </plus-avatar>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-avatar image="https://i.pravatar.cc/50" alt="User Name">
  </plus-avatar>
</template>

Svelte

<plus-avatar image="https://i.pravatar.cc/50" alt="User Name">
</plus-avatar>

HTML

<plus-avatar image="https://i.pravatar.cc/50" alt="User Name">
</plus-avatar>

Size

The size prop controls the dimensions of the avatar. It accepts predefined values (xs, sm, md, lg, xl) or any valid CSS size unit.

Show code

React

import { PlusAvatar } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusAvatar size="xs">
      </PlusAvatar>
      <PlusAvatar size="sm">
      </PlusAvatar>
      <PlusAvatar size="md">
      </PlusAvatar>
      <PlusAvatar size="lg">
      </PlusAvatar>
      <PlusAvatar size="xl">
      </PlusAvatar>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-avatar size="xs">
    </plus-avatar>
    <plus-avatar size="sm">
    </plus-avatar>
    <plus-avatar size="md">
    </plus-avatar>
    <plus-avatar size="lg">
    </plus-avatar>
    <plus-avatar size="xl">
    </plus-avatar>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-avatar size="xs">
  </plus-avatar>
  <plus-avatar size="sm">
  </plus-avatar>
  <plus-avatar size="md">
  </plus-avatar>
  <plus-avatar size="lg">
  </plus-avatar>
  <plus-avatar size="xl">
  </plus-avatar>
</template>

Svelte

<plus-avatar size="xs">
</plus-avatar>
<plus-avatar size="sm">
</plus-avatar>
<plus-avatar size="md">
</plus-avatar>
<plus-avatar size="lg">
</plus-avatar>
<plus-avatar size="xl">
</plus-avatar>

HTML

<plus-avatar size="xs">
</plus-avatar>
<plus-avatar size="sm">
</plus-avatar>
<plus-avatar size="md">
</plus-avatar>
<plus-avatar size="lg">
</plus-avatar>
<plus-avatar size="xl">
</plus-avatar>

Shape

The shape prop determines the overall shape of the avatar.

Show code

React

import { PlusAvatar } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusAvatar shape="circle" image="https://i.pravatar.cc/50">
      </PlusAvatar>
      <PlusAvatar shape="square" image="https://i.pravatar.cc/50">
      </PlusAvatar>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-avatar shape="circle" image="https://i.pravatar.cc/50">
    </plus-avatar>
    <plus-avatar shape="square" image="https://i.pravatar.cc/50">
    </plus-avatar>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-avatar shape="circle" image="https://i.pravatar.cc/50">
  </plus-avatar>
  <plus-avatar shape="square" image="https://i.pravatar.cc/50">
  </plus-avatar>
</template>

Svelte

<plus-avatar shape="circle" image="https://i.pravatar.cc/50">
</plus-avatar>
<plus-avatar shape="square" image="https://i.pravatar.cc/50">
</plus-avatar>

HTML

<plus-avatar shape="circle" image="https://i.pravatar.cc/50">
</plus-avatar>
<plus-avatar shape="square" image="https://i.pravatar.cc/50">
</plus-avatar>

Fallback Behavior

When an image is not provided or fails to load, the avatar displays fallback content based on the fallbackStrategy prop. You can provide text for initials or use the default icon (customizable via the icon prop).

Show code

React

import { PlusAvatar } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusAvatar text="Murat Polat Özkan" fallbackStrategy="text">
      </PlusAvatar>
      <PlusAvatar text="Single" fallbackStrategy="text">
      </PlusAvatar>
      <PlusAvatar icon="ghost">
      </PlusAvatar>
      <PlusAvatar>
      </PlusAvatar>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-avatar text="Murat Polat Özkan" fallback-strategy="text">
    </plus-avatar>
    <plus-avatar text="Single" fallback-strategy="text">
    </plus-avatar>
    <plus-avatar icon="ghost">
    </plus-avatar>
    <plus-avatar>
    </plus-avatar>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-avatar text="Murat Polat Özkan" fallback-strategy="text">
  </plus-avatar>
  <plus-avatar text="Single" fallback-strategy="text">
  </plus-avatar>
  <plus-avatar icon="ghost">
  </plus-avatar>
  <plus-avatar>
  </plus-avatar>
</template>

Svelte

<plus-avatar text="Murat Polat Özkan" fallback-strategy="text">
</plus-avatar>
<plus-avatar text="Single" fallback-strategy="text">
</plus-avatar>
<plus-avatar icon="ghost">
</plus-avatar>
<plus-avatar>
</plus-avatar>

HTML

<plus-avatar text="Murat Polat Özkan" fallback-strategy="text">
</plus-avatar>
<plus-avatar text="Single" fallback-strategy="text">
</plus-avatar>
<plus-avatar icon="ghost">
</plus-avatar>
<plus-avatar>
</plus-avatar>

Visual Sections

Layout & Spacing

Proper layout and spacing are crucial for integrating avatars seamlessly into the UI.

Light & Dark Mode

The Avatar component adapts to both light and dark themes.

Accessibility (a11y)

• Keyboard Behavior: The component itself is not typically interactive, but if used within an interactive element (like a button or link), ensure that element follows standard keyboard navigation patterns.
• Screen Reader: The role="img" is automatically applied. Provide meaningful alternative text via the alt prop, especially when an image is used. If alt is absent, the component attempts to use the text prop or a generic label, but explicit alt text is always recommended for clarity.
• Developer Actions: Always provide a descriptive alt prop when using the image prop. Ensure sufficient color contrast between the avatar background and foreground (text/icon) if customizing colors.

API Reference

Properties

Name	Type	Default	Description
image	string	undefined	URL of the avatar image.
alt	string	undefined	Alternative text for the image.
shape	'circle' | 'square'	'circle'	Shape of the avatar.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | string	'md'	Size of the avatar (predefined or custom CSS unit).
icon	string	'fa-solid fa-user'	CSS class for the fallback icon.
invert	boolean	false	Toggles the inverted color scheme.
text	string	undefined	Text to display as initials.
fallbackStrategy	'icon' | 'text' | 'custom'	'icon'	Strategy when image fails to load.

Events

Name	Payload Type	Description
error	CustomEvent<void>	Fired when the image fails to load.
load	CustomEvent<void>	Fired when the image loads.

Slots

Name	Description
(default)	Main content area (image, icon, or text).
fallback	Custom content for fallbackStrategy='custom'.

CSS Custom Properties

Name	Description
--text-color	Text color for initials or icon.
--bg-default	Default background color.

Shadow Parts

Name	Description
base	The main container element.

Join the Community

Plus UI is built by the community. Join us on our platforms to contribute, get help, and stay up to date.

Figma GitHub Discord Twitter Open Collective