Skip to content
txbrendan/ui

Avatar

beta

A round profile photo that falls back to initials in one of eight soft tints, picked from the name.

Preview

Texture

tint

by name

size

photo

failed

solid

initials

Install

  1. 1. Add the registry to components.json, once per app. Without it, the shadcn CLI looks up @txbrendan in a public list that txbrendan/ui does not control.

    npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"

  2. 2. Add the theme, once per app. It replaces your color tokens with ones checked for contrast.

    npx shadcn@latest add @txbrendan/theme

  3. 3. Add the component.

    npx shadcn@latest add @txbrendan/avatar

Use it for

  • Showing who someone is, next to their name: in rows, tables, comments, and cards.
  • A team or company, with solid set to its own color.
  • Pass the full name. It names the avatar for screen readers, and it picks the initials and the tint.
  • Use Person when the name shows beside the avatar. It hides the avatar from screen readers, so the name is read once.

Avoid it for

  • A face with no name anywhere near it. A person's name always has their avatar beside it, and the other way round.
  • Many overlapping faces for a count, like who is going. Use AvatarStack.
  • A logo or an icon that is not a person or a team. Use the image or the icon itself.
  • Setting tint to say something, like red for a problem. Tints only tell people apart.
  • A light solid color, like white or pale yellow. The initials are near white, so they would not show. Use the photo or logo as src.

Props

  • name

    Required. The full name. It names the avatar and gives the initials and the tint.

    string

  • src

    Photo URL. The initials show until it loads, and stay if it fails. The photo fades in.

    string

  • size

    21, 28, or 36px at the default density. Density scales it.

    "sm" | "md" | "lg" · default "md"

  • tint

    0 to 7. Picks a tint instead of the one the name gives. The same name always gets the same tint.

    number

  • solid

    A team's own color, as any CSS color, behind light initials. A thin ring keeps a black or white color off the page.

    string

  • initials

    How many letters show. Use 1 where faces overlap.

    1 | 2 · default 2

  • texture

    dither draws the photo as dots over its tint, gradient fades it from the top, and grain speckles it. Initials stay flat. Hover fills gradient and grain in. Left out, the avatar follows the Texture around it.

    "flat" | "dither" | "gradient" | "grain"

  • className

    Extra classes. Later classes win, so className='size-16' makes it bigger.

    string

Accessibility

  • Renders a <span role="img"> named by name, so screen readers read the name once and skip the letters.
  • The photo has an empty alt, since the avatar's own name already says who it is.
  • When the name shows next to the avatar, pass aria-hidden, or use Person, which does it for you.
  • The first five tints are the tones' soft pairs, held to 4.5:1 by the theme tests. The other three mix a chart color into the card, and avatar.test.tsx holds their initials to 4.5:1 in light and dark.
  • A solid color comes from your app, so its contrast is yours to check. The initials use the near-white text color of the solid tones.

Examples

With initials

<Avatar name="Sam Carter" />

With a photo

<Avatar name="Kate Clarke" src="/people/kate.jpg" size="lg" />

A grain photo that clears on hover

<Avatar name="Kate Clarke" src="/people/kate.jpg" size="lg" texture="grain" />

A solid brand color

<Avatar name="Design studio" solid="#0b3d91" />

Beside a name

<span className="inline-flex items-center gap-2">
  <Avatar name="Josh Tait" aria-hidden />
  Josh Tait
</span>