Skip to content

Avatar

Get Ritla UI

Represents a person or account with a photo, initials or a generic placeholder, and can carry a badge for edit, verified or online.

Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add avatar

    Also works with shadcn: npx shadcn@latest add @ritla/avatar

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

avatar.tsx
import { Avatar } from "@/components/ui/avatar";<Avatar name="Layla Haddad" src={photoUrl} status="verified" />

Examples

Types, sizes and statuses

A photo, initials from name, type="placeholder", or type="add" to add a photo; five sizes; and status for edit, verified or online.

EnglishMirroredArabic
LTR →

When the photo doesn't load

The initials show while the photo loads or if it fails: one Arabic letter for an Arabic name, two letters for a Latin one, initials to set them; the placeholder when there's no name.

EnglishMirroredArabic
LTR →

Avatar group

AvatarGroup overlaps them, the inline-start one on top. max shows that many and adds the rest to count, drawn as "+N" in the page numerals. Group sizes sm, md and lg hold xs, sm and md avatars.

EnglishMirroredArabic
LTR →

API reference

Avatar

PropTypeDefaultDescription
namestringNoneThe person's or account's name: the text alternative and the initials.
srcstringNoneFigma's Type = Photo.
type"placeholder" | "initials" | "add" | "company-logo"NoneFigma's Type without a photo.
logoReactNodeNoneFigma's Logo, with type="company-logo": decorative; name is the text alternative.
initialsstringNoneOverrides the initials from the name.
size"xxs" | "xs" | "sm" | "md" | "lg""md"24, 32, 40, 48 and 60px.
status"none" | "edit" | "verified" | "online""none"Figma's Status: a badge at the bottom inline-end corner.
decorativebooleanfalseHides it from screen readers when the name is visible next to it.

AvatarGroup

PropTypeDefaultDescription
size"sm" | "md" | "lg""sm"Figma's group Size: xs, sm or md avatars.
countnumber0Figma's Count: how many more people are not shown.
maxnumberNoneShows at most this many avatars; the rest join the count.
labelstringNoneThe group's name for screen readers ("Project members").
countLabel(count) => ReactNodeNoneRead after the names. Default: "and 9 more".

Usage guidelines

An avatar stands for a person or an account with a photo or initials. Which type, which size, initials for Arabic names, status badges, where the badge sits in Arabic, and the checks before handoff.

1. Which type

Show the best thing you have: a photo, then initials from the name, then the generic placeholder. Add is a slot to upload a photo, only where people manage their own profile.

TypeUse
PhotoPeople and accounts with a picture. While it loads, or if it fails, initials show in its place.
InitialsPeople with a name but no photo.
PlaceholderNo photo and no name yet, such as an invited contact.
AddThe user's own profile before a photo is uploaded; pressing it opens the upload.

2. Sizes

Each context has its size. Keep one size in a list so rows line up.

SizeUse
xxs · 24Inline with text, stacked groups, comments.
xs · 32Table rows and dense lists.
sm · 40List items and menus.
md · 48Cards, headers and contact rows.
lg · 60Profile headers and account screens.

3. Initials and Arabic names

Initials must be readable in the name's own script. For an Arabic name, show its first Arabic letter; for a Latin name, the first letters of the first and last words. Code works this out from the name. The avatar's accessible name is the person's full name.

Initials in the name's script

An Arabic contact without a photo.

Do: One Arabic letterThe first letter of the Arabic name, read the way its owner writes it.
Don't: Latin initials for an Arabic nameTwo transliterated letters say nothing to an Arabic reader.

Do

  • Use one Arabic letter for an Arabic name.
  • Use two letters for a Latin name: Layla Haddad becomes LH.
  • Pass the full name; code derives the initials and the accessible name.

Don't

  • Transliterate an Arabic name into Latin initials.
  • Show three or more letters.
  • Use initials when a photo is available.

4. Status badges

A badge adds one fact: Edit (the person can change the photo), Verified (the account is confirmed), Online (available now). It sits at the bottom inline-end corner. Code reads it with the name, “Layla Haddad, Verified”, so the badge is never the only signal.

Do

  • Use one badge at a time, only when it matters to the task.
  • Reserve Verified for accounts that really are verified.
  • Show online status in text too where it matters, such as a chat header.

Don't

  • Stack several badges on one avatar.
  • Rely on the green dot alone to say someone is online.
  • Use the badge for counts; use a Badge next to the name.

5. Arabic and RTL

In the RTL variant the badge moves to the bottom left, which is the inline end in Arabic, and initials use one Arabic letter. Photos never mirror: a face flipped is a different face.

The badge sits at the inline end

A verified account in Arabic.

Do: RTL variantThe check badge is at the bottom left, the end of the Arabic line.
Don't: English avatar on an Arabic screenThe badge sits at the start of the Arabic line, before the name is read.

Before handoff

  • Photo, initials and placeholder fallbacks are designed.
  • One size per list.
  • Arabic names use one Arabic letter; Latin names two letters.
  • Arabic screens use the RTL variant, with the badge at the bottom left.

Accessibility

ARIA

  • role="img" named by the person and the status in the page language (“Layla Haddad, Verified”); the green dot is never the only signal.
  • The edit badge is decorative: the button around the avatar names the action (“Change photo”).
  • The group is a named role="group"; each avatar reads its name, then "and 9 more"; the drawn "+9" itself is hidden from screen readers.

Do

  • Pass the full name, so the avatar is announced by name.
  • Hide it from screen readers when the name is written right next to it (decorative).
  • Keep initials readable: text/gray/muted on the container reaches AA.

Don't

  • Leave the avatar unnamed.
  • Announce both the avatar and the name next to it.

Arabic and RTL notes

Mirrors

  • The badge sits at the bottom inline-end corner: on the left in Arabic.
  • In a group the avatars start on the right in Arabic, each on top of the next, the count last on the left.

Does not mirror

  • The photo, the verified seal, the pencil and a company logo don't mirror.
Numerals
The group's count follows the page's numerals ("+٩"), with the plus before the number in both directions.
Arabic typography
An Arabic name gets one Arabic letter (ل for Layla), never two Latin letters; initials are SemiBold, in IBM Plex Sans Arabic for Arabic.
Mixed-direction text
Put the visible name next to it in <bdi>, so a Latin name in an Arabic list stays intact.

Do

  • The RTL variant in Arabic lists, with the badge at the bottom left.
  • Keep photos exactly as uploaded.

Don't

  • Mirror the photo.
  • Keep the badge at the bottom right on Arabic screens.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space
  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)