Avatar

Image with an initials fallback, a presence dot, and a group that collapses into a +N counter.

Source: 1 file
Dependencies: none
Playground: yes

Examples

Every variant of the shipped component, live. Switch the layout to read them as a table or one at a time, and open Code for the file behind them.

01Size

<Avatar size="xs | sm | md | lg | xl" />

02Fallback

GHATUI

<Avatar alt="Grace Hopper" /> → initials

03Rounded

<Avatar rounded="md | lg | xl | full" />

04Status

<Avatar status="online | offline | busy | away" />

05Ring

<Avatar ring />

06Group

GH+2

<AvatarGroup max={4}>…</AvatarGroup>

07Group shape & size

<AvatarGroup size="sm" rounded="md" />

Installation

One package for the whole library — run this once and every component on this site is importable. Adding the tokens to your stylesheet is the other half; the installation guide covers it.

npm install kipui

import { Avatar, AvatarGroup } from "kipui";

Peer dependencies

react 19

react-dom 19

tailwindcss 4

Bundled dependencies

None beyond the peers above.

Usage

avatar-example.tsx

import { Avatar, AvatarGroup } from "kipui";

<AvatarGroup max={3}>
  <Avatar src="/amelia.jpg" alt="Amelia Evans" status="online" />
  <Avatar alt="Noah Mitchell" />
  <Avatar alt="Grace Foster" />
  <Avatar alt="Owen Hayes" />
</AvatarGroup>

`alt` is required whenever `src` is set, and doubles as the source of the fallback initials.
`AvatarGroup` sets `ring` on its children automatically — you don't pass it yourself.

Playground

Change the props and the snippet underneath updates with them.

Preview

Props

sizelg

roundedfull

statusonline

altAmelia Evans

ring

<Avatar
  size="lg"
  rounded="full"
  status="online"
  alt="Amelia Evans"
/>

API reference

Transcribed from the component's own types. Props with no default are required.

Avatar

Prop	Default	Description
srcstring	required	Image source.
altstring	required	Required with `src`; also derives the fallback initials.
fallbackstring	required	Explicit fallback content instead of initials.
size"xs" \| "sm" \| "md" \| "lg" \| "xl"	"md"	Diameter and type scale.
rounded"full" \| "lg" \| "md"	"full"	Corner radius.
status"online" \| "offline" \| "busy" \| "away"	required	Presence dot.
ringboolean	false	Ring around the avatar. Set automatically inside AvatarGroup.

AvatarGroup

Prop	Default	Description
maxnumber	required	Avatars shown before collapsing into a +N counter.
size"xs" \| "sm" \| "md" \| "lg" \| "xl"	"md"	Applied to every child.
rounded"sm" \| "md" \| "lg" \| "full"	"full"	Applied to every child.