Avatar
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
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add avatarAlso works with shadcn:
npx shadcn@latest add @ritla/avatarDependencies it brings
@base-ui/react@phosphor-icons/reactOr 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
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.
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.
Company logo
type="company-logo": a rounded square holding logo (or a src image, fitted, never cropped), with the company as name. Use the logo's on-light version; with no logo, the initials show.
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.
API reference
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | None | The person's or account's name: the text alternative and the initials. |
src | string | None | Figma's Type = Photo. |
type | "placeholder" | "initials" | "add" | "company-logo" | None | Figma's Type without a photo. |
logo | ReactNode | None | Figma's Logo, with type="company-logo": decorative; name is the text alternative. |
initials | string | None | Overrides 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. |
decorative | boolean | false | Hides it from screen readers when the name is visible next to it. |
AvatarGroup
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "md" | "lg" | "sm" | Figma's group Size: xs, sm or md avatars. |
count | number | 0 | Figma's Count: how many more people are not shown. |
max | number | None | Shows at most this many avatars; the rest join the count. |
label | string | None | The group's name for screen readers ("Project members"). |
countLabel | (count) => ReactNode | None | Read 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.
| Type | Use |
|---|---|
| Photo | People and accounts with a picture. While it loads, or if it fails, initials show in its place. |
| Initials | People with a name but no photo. |
| Placeholder | No photo and no name yet, such as an invited contact. |
| Add | The 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.
| Size | Use |
|---|---|
xxs · 24 | Inline with text, stacked groups, comments. |
xs · 32 | Table rows and dense lists. |
sm · 40 | List items and menus. |
md · 48 | Cards, headers and contact rows. |
lg · 60 | Profile 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
- 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.
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/mutedon 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.
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)