Entity Avatar

"use client"

import { EntityAvatar } from "@/components/ui/entity-avatar"

The EntityAvatar component shows who or what is on the other side of a payment: a merchant or service logo, a person's initials, or a country or currency code. Logos are shown in greyscale so lists of transactions and payees stay calm. Use it in transaction rows, payee lists, and profile headers. Pick Avatar instead when you need a badge, a group, or full-color photos of people.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/entity-avatar
Copy

Usage#

Copyimport { EntityAvatar } from "@/components/ui/entity-avatar"

Copy<EntityAvatar name="Coffee Point" shape="square" />

Features#

• Initials built from name: "Coffee Point" becomes "CP", "alex" becomes "A"
• A short code instead of initials, such as "DE" or "USD", up to 4 characters
• Logos and photos in greyscale, with the initials or code shown when the image fails to load
• Round for people and countries, square for merchants, services, and apps
• Four sizes, from a 32px list mark to a 112px profile header
• Hidden from assistive tech next to a visible name, labelled when it stands alone

Shape#

Use the default shape="circle" for people and countries, and shape="square" for merchants, services, and apps.

import { EntityAvatar } from "@/components/ui/entity-avatar"

export function EntityAvatarShape() {

Code#

Pass code to show a country, currency, or asset code instead of initials. Codes longer than two characters get a smaller type size so they fit.

import { EntityAvatar } from "@/components/ui/entity-avatar"

export function EntityAvatarCode() {

Image#

Pass src for a logo or photo. It is shown in greyscale. If it fails to load, the initials or code show instead.

PS

HB

Copy

import { EntityAvatar } from "@/components/ui/entity-avatar"

// A coloured logo, to show that the avatar renders it in greyscale.

View Code

Size#

Use size to switch between sm (32px), default (40px), lg (48px), and xl (112px). Keep one size across a list, and use xl for profile headers.

import { EntityAvatar } from "@/components/ui/entity-avatar"

export function EntityAvatarSize() {

Label#

When the avatar stands alone, with no name written next to it, pass a label. The avatar then becomes an image with that name.

import { EntityAvatar } from "@/components/ui/entity-avatar"

export function EntityAvatarLabel() {

Accessibility#

EntityAvatar is decorative by default. The usual place for it is next to the name it stands for, so it is hidden from assistive tech with aria-hidden and the name is read once, from the text.

Label avatars that stand alone#

When there is no visible name, such as a row of payees or a profile header without a title, pass label. The avatar gets role="img" and the label as its accessible name.

Copy<EntityAvatar name="Jordan Lee" label="Jordan Lee" size="xl" />

Images are never announced#

The image always has an empty alt, and the initials or code are hidden too, so screen readers never read "CP" or a file name. Put anything people need to hear in the visible name or in label.

API Reference#

EntityAvatar#

Renders an Avatar with an optional image and the initials or code as the fallback.