Primitive / Atomstable

Avatar

Profile image with glassmorphic variants, status indicators, grouped stacking, and copy-ready Tailwind recipes.

@glinui/uiComponent: avatar

Installation$

Package Manager$

pnpm add @glinui/ui @glinui/tokens

Registry$

pnpm dlx @glinui/cli@latest add avatar

Usage$

Avatar renders an image or fallback with a predictable priority: fallback prop > children > first character of alt > "?".

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarBasicDemo() {
4return <Avatar src="https://api.dicebear.com/9.x/adventurer/svg?seed=Nova" alt="Nova" />
5}

Examples$

Glass Variants$

Seven surface variants matching the design system. Glass and liquid use backdrop-blur with refraction edges.

DFGLLQMTGWOLGH

Language

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarVariantsDemo() {
4return (
5  <div className="flex items-center gap-4">
6    <Avatar fallback="DF" alt="Default" variant="default" />
7    <Avatar fallback="GL" alt="Glass" variant="glass" />
8    <Avatar fallback="LQ" alt="Liquid" variant="liquid" />
9    <Avatar fallback="MT" alt="Matte" variant="matte" />
10    <Avatar fallback="GW" alt="Glow" variant="glow" />
11    <Avatar fallback="OL" alt="Outline" variant="outline" />
12    <Avatar fallback="GH" alt="Ghost" variant="ghost" />
13  </div>
14)
15}

With Images$

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarImagesDemo() {
4return (
5  <div className="flex items-center gap-4">
6    <Avatar src="https://api.dicebear.com/9.x/adventurer/svg?seed=Nova" alt="Nova" variant="default" />
7    <Avatar src="https://api.dicebear.com/9.x/lorelei/svg?seed=Kai" alt="Kai" variant="glass" />
8    <Avatar src="https://api.dicebear.com/9.x/bottts/svg?seed=Glin" alt="Glin" variant="liquid" />
9    <Avatar src="https://api.dicebear.com/9.x/pixel-art/svg?seed=Leo" alt="Leo" variant="matte" />
10    <Avatar src="https://api.dicebear.com/9.x/thumbs/svg?seed=Aria" alt="Aria" variant="glow" />
11  </div>
12)
13}

Sizes$

Six sizes from xs (24px) to 2xl (80px).

XSSMMDLGXL2X

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarSizeDemo() {
4return (
5  <div className="flex items-end gap-3">
6    <Avatar size="xs" fallback="XS" alt="Extra small" />
7    <Avatar size="sm" fallback="SM" alt="Small" />
8    <Avatar size="md" fallback="MD" alt="Medium" />
9    <Avatar size="lg" fallback="LG" alt="Large" />
10    <Avatar size="xl" fallback="XL" alt="Extra large" />
11    <Avatar size="2xl" fallback="2X" alt="Double extra large" />
12  </div>
13)
14}

Radius Styles$

FULGMDSQ

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarRadiusDemo() {
4return (
5  <div className="flex items-center gap-4">
6    <Avatar radius="full" fallback="FU" variant="glass" />
7    <Avatar radius="lg" fallback="LG" variant="glass" />
8    <Avatar radius="md" fallback="MD" variant="glass" />
9    <Avatar radius="square" fallback="SQ" variant="glass" />
10  </div>
11)
12}

Status Indicator$

Show online, offline, busy, or away status with an auto-positioned dot.

Language

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarStatusDemo() {
4return (
5  <div className="flex items-center gap-4">
6    <Avatar src="..." alt="Online" status="online" />
7    <Avatar src="..." alt="Away" status="away" />
8    <Avatar src="..." alt="Busy" status="busy" />
9    <Avatar src="..." alt="Offline" status="offline" />
10  </div>
11)
12}

Avatar Group$

Stack avatars with overlap. Set max to cap visible count with a +N overflow indicator.

Language

TSX

1import { Avatar, AvatarGroup } from "@glinui/ui"
2
3export function AvatarGroupDemo() {
4return (
5  <div className="space-y-6">
6    <AvatarGroup>
7      <Avatar src="..." alt="Nova" />
8      <Avatar src="..." alt="Kai" />
9      <Avatar src="..." alt="Glin" />
10      <Avatar src="..." alt="Leo" />
11    </AvatarGroup>
12
13    <AvatarGroup max={3}>
14      <Avatar src="..." alt="Nova" />
15      <Avatar src="..." alt="Kai" />
16      <Avatar src="..." alt="Glin" />
17      <Avatar src="..." alt="Leo" />
18      <Avatar src="..." alt="Aria" />
19    </AvatarGroup>
20  </div>
21)
22}

Glass Variants with Status$

Combine glass surfaces with status indicators for rich profile displays.

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarGlassStatusDemo() {
4return (
5  <div className="flex items-center gap-4">
6    <Avatar src="..." alt="Nova" variant="glass" size="lg" status="online" />
7    <Avatar src="..." alt="Kai" variant="liquid" size="lg" status="away" />
8    <Avatar src="..." alt="Glin" variant="matte" size="lg" status="busy" />
9    <Avatar src="..." alt="Leo" variant="glow" size="lg" status="offline" />
10  </div>
11)
12}

Copy-Paste Recipes$

Drop these Tailwind classes directly into your markup for common avatar patterns.

Language

HTML

1/* ── Profile card avatar ──────────────────── */
2<img class="
3h-16 w-16 rounded-full border-2 border-white/20
4[border-top-color:var(--glass-refraction-top)]
5bg-[linear-gradient(155deg,rgb(255_255_255_/_0.62),rgb(245_245_245_/_0.36))]
6backdrop-blur-md backdrop-saturate-[180%]
7shadow-[0_0_0_1px_rgb(255_255_255_/_0.2)_inset,0_6px_16px_-8px_rgb(2_6_23_/_0.25)]
8object-cover
9transition-transform duration-300 ease-[cubic-bezier(0.2,0,0,1)]
10hover:scale-105
11" />
12
13/* ── Sidebar nav avatar with glow ────────── */
14<div class="
15h-10 w-10 rounded-full
16border border-white/20 bg-neutral-900
17shadow-[0_0_0_1px_rgb(255_255_255_/_0.12)_inset,0_0_16px_rgb(255_255_255_/_0.15)]
18flex items-center justify-center
19text-sm font-semibold text-white
20transition-shadow duration-250
21hover:shadow-[0_0_0_1px_rgb(255_255_255_/_0.14)_inset,0_0_24px_rgb(255_255_255_/_0.25)]
22"/>
23
24/* ── Comment thread avatar (matte) ───────── */
25<img class="
26h-8 w-8 rounded-full
27border border-black/10
28bg-[linear-gradient(180deg,rgb(250_250_250),rgb(234_234_236))]
29shadow-[0_1px_0_rgb(255_255_255_/_0.92)_inset,0_4px_10px_-6px_rgb(15_23_42_/_0.22)]
30object-cover
31"/>
32
33/* ── Hero avatar with hover lift ─────────── */
34<img class="
35h-20 w-20 rounded-full
36border-2 border-white/20
37[border-top-color:var(--glass-refraction-top)]
38bg-[radial-gradient(circle_at_18%_16%,rgb(255_255_255_/_0.88),transparent_40%),linear-gradient(148deg,rgb(255_255_255_/_0.74),rgb(232_232_232_/_0.5))]
39backdrop-blur-xl backdrop-saturate-[180%]
40shadow-[0_0_0_1px_rgb(255_255_255_/_0.2)_inset,0_10px_24px_-8px_rgb(2_6_23_/_0.3)]
41object-cover
42transition-[transform,box-shadow] duration-300 ease-[cubic-bezier(0.2,0,0,1)]
43hover:-translate-y-1
44hover:shadow-[0_0_0_1px_rgb(255_255_255_/_0.24)_inset,0_16px_32px_-8px_rgb(2_6_23_/_0.35)]
45"/>

Image Error Recovery$

A broken image source falls back instantly, and if src later changes to a valid URL, the image renders again.

TSX

1import { Avatar } from "@glinui/ui"
2
3export function AvatarErrorDemo() {
4return (
5  <div className="flex items-center gap-3">
6    <Avatar src="/broken-src.png" alt="Broken" fallback="BR" variant="matte" />
7    <Avatar src="https://api.dicebear.com/9.x/adventurer/svg?seed=Replaced" alt="Recovered" variant="glass" />
8  </div>
9)
10}

Accessibility$

Provide a meaningful alt for identity-bearing avatars.
Keep consistent avatar sizes in list/table contexts to reduce visual noise.
Fallback initials ensure content remains identifiable when images fail.
Status indicators include aria-label for screen readers.

Reduced Motion$

Transition effects on hover (scale, shadow) respect prefers-reduced-motion via the motion-reduce:transition-none utility.

API Reference$

Avatar$

Prop	Type	Required	Default	Description
`alt`	`string`	No	`""`	Auto-generated from TypeScript source.
`fallback`	`string`	No	`-`	Auto-generated from TypeScript source.
`fallbackClassName`	`string`	No	`-`	Auto-generated from TypeScript source.
`imgClassName`	`string`	No	`-`	Auto-generated from TypeScript source.
`radius`	`"full" \| "lg" \| "md" \| "square"`	No	`"full"`	Variant option from avatarVariants.
`ring`	`boolean`	No	`-`	Ring color for grouped avatars or emphasis
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	No	`"md"`	Variant option from avatarVariants.
`src`	`string`	No	`-`	Auto-generated from TypeScript source.
`status`	`AvatarStatus`	No	`-`	Online/offline status indicator
`variant`	`"default" \| "glass" \| "liquid" \| "matte" \| "glow" \| "outline" \| "ghost"`	No	`"default"`	Variant option from avatarVariants.

AvatarGroup$

Prop	Type	Required	Default	Description
`max`	`number`	No	`-`	Max avatars to show before +N overflow
`spacing`	`"tight" \| "normal" \| "loose"`	No	`"normal"`	Overlap spacing

Source$

TSX

1import { Avatar, AvatarGroup } from "@glinui/ui"

packages/ui/src/components/avatar.tsx

packages/ui/src/tests/avatar.test.tsx

Generated API Snapshot

Beta

Auto-extracted from TypeScript source in packages/ui/src/components/avatar.tsx. This section is in beta and may lag behind hand-curated docs. Regenerate with pnpm --filter @glinui/docs api:generate.

Generated: 2026-02-19T17:59:28.468Z · Full index: /docs/api-metadata

Primary Props Type

AvatarProps

`AvatarGroupProps`

Prop	Type	Required	Default	Description
`max`	`number`	No	`-`	Max avatars to show before +N overflow
`spacing`	`"tight" \| "normal" \| "loose"`	No	`"normal"`	Overlap spacing

`AvatarProps`

Prop	Type	Required	Default	Description
`alt`	`string`	No	`""`	-
`fallback`	`string`	No	`-`	-
`fallbackClassName`	`string`	No	`-`	-
`imgClassName`	`string`	No	`-`	-
`radius`	`"full" \| "lg" \| "md" \| "square"`	No	`"full"`	Variant option from avatarVariants.
`ring`	`boolean`	No	`-`	Ring color for grouped avatars or emphasis
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	No	`"md"`	Variant option from avatarVariants.
`src`	`string`	No	`-`	-
`status`	`AvatarStatus`	No	`-`	Online/offline status indicator
`variant`	`"default" \| "glass" \| "liquid" \| "matte" \| "glow" \| "outline" \| "ghost"`	No	`"default"`	Variant option from avatarVariants.