Avatar

A round user image, or a placeholder with an icon or initials when there is none.

Installation

bun add @harmo-ui/css @harmo-ui/react

npm install @harmo-ui/css @harmo-ui/react

pnpm add @harmo-ui/css @harmo-ui/react

yarn add @harmo-ui/css @harmo-ui/react

bunx harmo-ui add avatar

npx harmo-ui add avatar

pnpm dlx harmo-ui add avatar

yarn dlx harmo-ui add avatar

Usage

import type { CSSProperties } from "react";
import { Avatar } from "@harmo-ui/react";

<Avatar src="images/imran.webp" alt="Imran Hajiyev" />
<Avatar alt="Imran Hajiyev">IH</Avatar>
<Avatar alt="Imran Hajiyev" style={{ "--harmo-avatar-size": "4rem" } as CSSProperties}>
  IH
</Avatar>

Examples

This site is using your theme

Image, icon, or initials

An image covers the circle. Without one, a placeholder shows an icon or initials on a soft gray. Name an image with alt, and a placeholder with role="img" and aria-label.

<>
  <Avatar src="images/imran.webp" alt="Imran Hajiyev" />
  <Avatar alt="Imran Hajiyev">
    <UserIcon />
  </Avatar>
  <Avatar alt="Imran Hajiyev">IH</Avatar>
</>

<img class="havatar" src="images/imran.webp" alt="Imran Hajiyev" />
<span class="havatar" role="img" aria-label="Imran Hajiyev">
  <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" focusable="false">
    <path d="M12 12.75C8.83 12.75 6.25 10.17 6.25 7C6.25 3.83 8.83 1.25 12 1.25C15.17 1.25 17.75 3.83 17.75 7C17.75 10.17 15.17 12.75 12 12.75Z" fill="currentColor" />
    <path d="M20.59 22.75c-.41 0-.75-.34-.75-.75 0-3.45-3.52-6.25-7.84-6.25-4.32 0-7.84 2.8-7.84 6.25 0 .41-.34.75-.75.75s-.75-.34-.75-.75c0-4.27 4.19-7.75 9.34-7.75s9.34 3.48 9.34 7.75c0 .41-.34.75-.75.75Z" fill="currentColor" />
  </svg>
</span>
<span class="havatar" role="img" aria-label="Imran Hajiyev">IH</span>

Sizes

40px by default. Override --harmo-avatar-size on the element and its content scales with it: initials are 40% of the size, and an icon 62.5% of the space inside the border.

IHIHIH

<>
  <Avatar alt="Imran Hajiyev" style={{ "--harmo-avatar-size": "4rem" } as CSSProperties}>
    IH
  </Avatar>
  <Avatar alt="Imran Hajiyev" style={{ "--harmo-avatar-size": "4rem" } as CSSProperties}>
    <UserIcon />
  </Avatar>
  <Avatar alt="Imran Hajiyev">IH</Avatar>
  <Avatar alt="Imran Hajiyev" style={{ "--harmo-avatar-size": "1.5rem" } as CSSProperties}>
    IH
  </Avatar>
</>

<span class="havatar" style="--harmo-avatar-size: 4rem" role="img" aria-label="Imran Hajiyev">IH</span>
<span class="havatar" style="--harmo-avatar-size: 4rem" role="img" aria-label="Imran Hajiyev">
  <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" focusable="false">
    <path d="M12 12.75C8.83 12.75 6.25 10.17 6.25 7C6.25 3.83 8.83 1.25 12 1.25C15.17 1.25 17.75 3.83 17.75 7C17.75 10.17 15.17 12.75 12 12.75Z" fill="currentColor" />
    <path d="M20.59 22.75c-.41 0-.75-.34-.75-.75 0-3.45-3.52-6.25-7.84-6.25-4.32 0-7.84 2.8-7.84 6.25 0 .41-.34.75-.75.75s-.75-.34-.75-.75c0-4.27 4.19-7.75 9.34-7.75s9.34 3.48 9.34 7.75c0 .41-.34.75-.75.75Z" fill="currentColor" />
  </svg>
</span>
<span class="havatar" role="img" aria-label="Imran Hajiyev">IH</span>
<span class="havatar" style="--harmo-avatar-size: 1.5rem" role="img" aria-label="Imran Hajiyev">IH</span>

Next to a name

When the name is shown beside it, hide the avatar from screen readers so the name isn't read twice: alt="" on an image, or aria-hidden="true" on a placeholder.

Imran Hajiyev

<>
  <Avatar src="images/imran.webp" alt="" />
  <span>Imran Hajiyev</span>
</>

<img class="havatar" src="images/imran.webp" alt="" />
<span>Imran Hajiyev</span>

API reference

React

<Avatar> renders the image with src, otherwise the placeholder, holding its children. Other props go to the image or the placeholder.

Prop	Effect
`src`	Renders the image, through `HarmoProvider`'s `imageComponent` (an `<img>` by default)
`alt`	Names it: the image's `alt`, or the placeholder's `role="img"` and `aria-label`. `alt=""` hides either from screen readers, for an avatar next to its name
`children`	The placeholder's initials or icon

HTML

An <img class="havatar"> with alt, or a <span class="havatar" role="img"> with aria-label for a placeholder, holding a direct <svg> or initials. Load avatar.css. It needs no script.

Hook	Effect
`--harmo-avatar-size` on the element	Size (default 2.5rem); text and icon scale with it

See Avatar's full contract.

Accessibility

An image needs alt with the person's name; a placeholder takes role="img" and aria-label.
When the name already appears next to the avatar, use alt="" (or aria-hidden="true" on a placeholder) so it isn't read twice.