A person or an account: their picture, or initials while it loads, when it fails or when there is none.

Web + MobileStableData display

Web and mobile — the same component for React and React Native. Stable: its API only changes in a major version.

When to use

Next to a name: comments, creators, members, the signed-in account in a header.
Avatar.Group to show who takes part (followers, collaborators) in little space.

When not to use

For a product, a video or a place: use an image in a card.Use instead: Card
As the only way to say who someone is: show their name too, or give the avatar an alt.

Installation

Install

npm install @krizaka/ui@beta @krizaka/tailwind@beta @krizaka/tokens@beta tailwindcss

Styles

@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";

Import

import { Avatar } from "@krizaka/ui/avatar";

Examples

With an image

A picture named by alt, with initials as fallback.

import { Avatar } from "@krizaka/ui/avatar";

// A self-contained portrait (no network).
const PORTRAIT =
  "data:image/svg+xml;utf8," +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80"><rect width="80" height="80" fill="#3b82f6"/>' +
      '<circle cx="40" cy="31" r="14" fill="#dbeafe"/><path d="M12 80a28 24 0 0 1 56 0z" fill="#dbeafe"/></svg>',
  );

export default function AvatarWithImage() {
  return <Avatar src={PORTRAIT} alt="Oussama" fallback="OA" />;
}

Fallback

No image: the initials.

import { Avatar } from "@krizaka/ui/avatar";

// No image (or while it loads, or when it fails): the initials.
export default function AvatarFallback() {
  return <Avatar fallback="OA" />;
}

Sizes

xs, sm, md (default), lg, xl.

import { Avatar } from "@krizaka/ui/avatar";

export default function AvatarSizes() {
  return (
    <div className="flex items-center gap-3">
      <Avatar size="xs" fallback="OA" />
      <Avatar size="sm" fallback="OA" />
      <Avatar size="md" fallback="OA" />
      <Avatar size="lg" fallback="OA" />
      <Avatar size="xl" fallback="OA" />
    </div>
  );
}

Group

Avatar.Group with max: the others become +n.

import { Avatar } from "@krizaka/ui/avatar";

const PORTRAIT =
  "data:image/svg+xml;utf8," +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80"><rect width="80" height="80" fill="#3b82f6"/>' +
      '<circle cx="40" cy="31" r="14" fill="#dbeafe"/><path d="M12 80a28 24 0 0 1 56 0z" fill="#dbeafe"/></svg>',
  );

// `max={3}`: the others become `+n`.
export default function AvatarGroup() {
  return (
    <Avatar.Group max={3} size="sm">
      <Avatar size="sm" src={PORTRAIT} alt="Oussama" />
      <Avatar size="sm" fallback="LM" />
      <Avatar size="sm" fallback="SK" />
      <Avatar size="sm" fallback="JD" />
      <Avatar size="sm" fallback="AR" />
    </Avatar.Group>
  );
}

Props

Avatar

Avatar (an image with a fallback) and Avatar.Group.

Prop	Type	Default	Description
`alt`	`string`	—	The image's text alternative (the person's name); empty when a visible name sits next to the avatar.
`fallback`	`ReactNode`	—	Shown while the image loads, when it fails or when there is none: initials, an icon.
`size`	`AvatarSize`	`md`	xs · sm · md · lg · xl.
`src`	`string \| null`	—	The image's URL; `null` or nothing shows the `fallback`.

AvatarGroup

Overlapping avatars; past max, a +n avatar counts the rest.

Prop	Type	Default	Description
`max`	`number`	—	How many avatars are shown; the rest becomes a `+n` avatar.
`size`	`AvatarSize`	—	The size of the `+n` avatar (match the avatars of the group).

AvatarRoot

Prop	Type	Default	Description
`alt`	`string`	—	The image's text alternative (the person's name); empty when a visible name sits next to the avatar.
`fallback`	`ReactNode`	—	Shown while the image loads, when it fails or when there is none: initials, an icon.
`size`	`AvatarSize`	`md`	xs · sm · md · lg · xl.
`src`	`string \| null`	—	The image's URL; `null` or nothing shows the `fallback`.

Accessibility

With alt, the picture is an image named by it; without alt, it is decorative — put the name in the text next to it.
The fallback initials are shown, not announced, when an alt names the person.

Best practices

Always pass a fallback (initials) on the web: images fail, and the layout should not jump.
Use one size per list: sm in dense lists, md by default, lg/xl on a profile.
In a group, set max so a long list ends with +n instead of overflowing.

Generated from the code of @krizaka/ui 2.0.0-beta.6: its meta.ts, its examples and its types.Edit this documentation on GitHub