Avatar

An image element with a fallback for representing the user.

HRPR

CNPRWZ

1
import {
2
  Avatar,
3
  AvatarBadge,
4
  AvatarFallback,
5
  AvatarGroup,
6
  AvatarGroupCount,
7
  AvatarImage,
8
} from "@/components/ui/pxl/avatar";
9

10
export default function AvatarDemo() {
11
  return (
12
    <div className="flex flex-row flex-wrap items-center gap-6 md:gap-12">
13
      <Avatar>
14
        <AvatarImage
15
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
16
          alt="@hero"
17
          className="grayscale group-hover/avatar:bg-primary group-hover/avatar:grayscale-0"
18
        />
19
        <AvatarFallback>HR</AvatarFallback>
20
      </Avatar>
21
      <Avatar>
22
        <AvatarImage
23
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/princess.png"
24
          alt="@princess"
25
          className="bg-success"
26
        />
27
        <AvatarFallback>PR</AvatarFallback>
28
        <AvatarBadge className="bg-success-foreground" />
29
      </Avatar>
30
      <AvatarGroup className="grayscale hover:grayscale-0">
31
        <Avatar>
32
          <AvatarImage
33
            src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
34
            alt="@hero"
35
            className="bg-primary"
36
          />
37
          <AvatarFallback>CN</AvatarFallback>
38
        </Avatar>
39
        <Avatar>
40
          <AvatarImage
41
            src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/princess.png"
42
            alt="@princess"
43
            className="bg-success"
44
          />
45
          <AvatarFallback>PR</AvatarFallback>
46
        </Avatar>
47
        <Avatar>
48
          <AvatarImage
49
            src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/wizard.png"
50
            alt="@wizard"
51
            className="bg-warning"
52
          />
53
          <AvatarFallback>WZ</AvatarFallback>
54
        </Avatar>
55
        <AvatarGroupCount>+3</AvatarGroupCount>
56
      </AvatarGroup>
57
    </div>
58
  )
59
}

Installation

Command
Manual

pnpm dlx shadcn@latest add pxl-ui/registry/avatar

Install the following dependencies:

pnpm add @base-ui/react

Copy and paste the following code into your project.

1
"use client";
2

3
import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
4
import { cva, type VariantProps } from "class-variance-authority";
5
import type { ComponentProps } from "react";
6

7
import { cn } from "@/lib/utils";
8

9
const avatarVariants = cva("group/avatar relative flex shrink-0 pixel-rounded select-none after:absolute after:inset-0 after:border after:border-border after:mix-blend-darken after:[clip-path:var(--px-shape)] dark:after:mix-blend-lighten", {
10
  variants: {
11
    size: {
12
      default: "size-8 pixel-size-md",
13
      xs: "size-4 pixel-size-sm",
14
      sm: "size-6 pixel-size-sm",
15
      md: "size-8 pixel-size-md",
16
      lg: "size-10 pixel-size-[3px]",
17
      xl: "size-12 pixel-size-lg",
18
    },
19
  },
20
  defaultVariants: {
21
    size: "default",
22
  },
23
});
24

25
function Avatar({
26
  className,
27
  size = "default",
28
  ...props
29
}: AvatarPrimitive.Root.Props & VariantProps<typeof avatarVariants>) {
30
  return (
31
    <AvatarPrimitive.Root
32
      data-slot="avatar"
33
      data-size={size}
34
      className={cn(
35
        avatarVariants({
36
          size,
37
        }),
38
        className,
39
      )}
40
      {...props}
41
    />
42
  );
43
}
44

45
function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) {
46
  return (
47
    <AvatarPrimitive.Image
48
      data-slot="avatar-image"
49
      className={cn(
50
        "aspect-square size-full [clip-path:var(--px-shape)] object-cover",
51
        className,
52
      )}
53
      {...props}
54
    />
55
  );
56
}
57

58
function AvatarFallback({
59
  className,
60
  ...props
61
}: AvatarPrimitive.Fallback.Props) {
62
  return (
63
    <AvatarPrimitive.Fallback
64
      data-slot="avatar-fallback"
65
      className={cn(
66
        "flex size-full items-center justify-center [clip-path:var(--px-shape)] bg-muted text-muted-foreground",
67
        "text-sm group-data-[size=sm]/avatar:text-xs",
68
        className,
69
      )}
70
      {...props}
71
    />
72
  );
73
}
74

75
function AvatarBadge({ className, ...props }: ComponentProps<"span">) {
76
  return (
77
    <span
78
      data-slot="avatar-badge"
79
      className={cn(
80
        "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center pixel-rounded pixel-size-sm bg-foreground text-background bg-blend-color border-2 border-background select-none",
81
        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
82
        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
83
        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
84
        className,
85
      )}
86
      {...props}
87
    />
88
  );
89
}
90

91
function AvatarGroup({ className, ...props }: ComponentProps<"div">) {
92
  return (
93
    <div
94
      data-slot="avatar-group"
95
      className={cn(
96
        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:border-2 *:data-[slot=avatar]:border-background *:data-[slot=avatar]:[clip-path:none]! *:data-[slot=avatar]:before:absolute *:data-[slot=avatar]:before:inset-0 *:data-[slot=avatar]:before:bg-background *:data-[slot=avatar]:before:content-['']",
97
        className,
98
      )}
99
      {...props}
100
    />
101
  );
102
}
103

104
function AvatarGroupCount({ className, ...props }: ComponentProps<"div">) {
105
  return (
106
    <div
107
      data-slot="avatar-group-count"
108
      className={cn(
109
        "relative isolate flex shrink-0 items-center justify-center [clip-path:none]! bg-background text-sm text-muted-foreground border-2 border-background before:absolute before:-z-10 before:inset-0 before:bg-muted before:content-[''] before:[clip-path:var(--px-shape)] after:absolute after:inset-0 after:border after:border-border after:mix-blend-darken after:[clip-path:var(--px-shape)] dark:after:mix-blend-lighten",
110
        "size-8 px-rounded-md pixel-size-md group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=lg]/avatar-group:pixel-size-[3px] group-has-data-[size=sm]/avatar-group:size-6 group-has-data-[size=sm]/avatar-group:pixel-size-sm [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
111
        className,
112
      )}
113
      {...props}
114
    />
115
  );
116
}
117

118
export {
119
  Avatar,
120
  AvatarBadge,
121
  AvatarFallback,
122
  AvatarGroup,
123
  AvatarGroupCount,
124
  AvatarImage,
125
};

Update the import paths to match your project setup.

Usage

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/pxl/avatar"

<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Composition

Use the following composition to build an Avatar:

Avatar
├── AvatarImage
├── AvatarFallback
└── AvatarBadge

Use the following composition to build an AvatarGroup:

AvatarGroup
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
└── AvatarGroupCount

Badge

Use the AvatarBadge component to add a badge to the avatar. The badge is positioned at the bottom right of the avatar.

1
import {
2
  Avatar,
3
  AvatarBadge,
4
  AvatarFallback,
5
  AvatarImage,
6
} from "@/components/ui/pxl/avatar"
7

8
export default function AvatarWithBadge() {
9
  return (
10
    <Avatar>
11
      <AvatarImage
12
        src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
13
        alt="@hero" />
14
      <AvatarFallback>HR</AvatarFallback>
15
      <AvatarBadge className="bg-success-foreground" />
16
    </Avatar>
17
  )
18
}

Use the className prop to add custom styles to the badge such as custom colors, sizes, etc.

<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
  <AvatarBadge className="bg-success-foreground" />
</Avatar>

Badge with Icon

You can also use an icon inside <AvatarBadge>.

1
import {
2
  Avatar,
3
  AvatarBadge,
4
  AvatarFallback,
5
  AvatarImage,
6
} from "@/components/ui/pxl/avatar"
7

8
export default function AvatarWithBadge() {
9
  return (
10
    <Avatar>
11
      <AvatarImage
12
        src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
13
        alt="@hero" />
14
      <AvatarFallback>HR</AvatarFallback>
15
      <AvatarBadge>
16
        <svg
17
          xmlns="http://www.w3.org/2000/svg"
18
          fill="currentColor"
19
          viewBox="0 0 24 24"
20
        >
21
          <path d="M13 11h7v2h-7v7h-2v-7H4v-2h7V4h2v7Z" />
22
        </svg>
23
      </AvatarBadge>
24
    </Avatar>
25
  )
26
}

Avatar Group

Use the AvatarGroup component to add a group of avatars.

HRPRWZ

1
import {
2
  Avatar,
3
  AvatarFallback,
4
  AvatarGroup,
5
  AvatarImage
6
} from "@/components/ui/pxl/avatar";
7

8
export default function AvatarGroupExample() {
9
  return (
10
    <AvatarGroup className="grayscale">
11
      <Avatar>
12
        <AvatarImage
13
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
14
          alt="@hero"
15
        />
16
        <AvatarFallback>HR</AvatarFallback>
17
      </Avatar>
18
      <Avatar>
19
        <AvatarImage
20
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/princess.png"
21
          alt="@princess"
22
        />
23
        <AvatarFallback>PR</AvatarFallback>
24
      </Avatar>
25
      <Avatar>
26
        <AvatarImage
27
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/wizard.png"
28
          alt="@wizard"
29
        />
30
        <AvatarFallback>WZ</AvatarFallback>
31
      </Avatar>
32
    </AvatarGroup>
33
  );
34
}

Avatar Group Count

Use <AvatarGroupCount> to add a count to the group.

HRPRWZ

1
import {
2
  Avatar,
3
  AvatarFallback,
4
  AvatarGroup,
5
  AvatarGroupCount,
6
  AvatarImage,
7
} from "@/components/ui/pxl/avatar";
8

9
export default function AvatarGroupCountExample() {
10
  return (
11
    <AvatarGroup className="grayscale">
12
      <Avatar>
13
        <AvatarImage
14
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
15
          alt="@hero"
16
        />
17
        <AvatarFallback>HR</AvatarFallback>
18
      </Avatar>
19
      <Avatar>
20
        <AvatarImage
21
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/princess.png"
22
          alt="@princess"
23
        />
24
        <AvatarFallback>PR</AvatarFallback>
25
      </Avatar>
26
      <Avatar>
27
        <AvatarImage
28
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/wizard.png"
29
          alt="@wizard"
30
        />
31
        <AvatarFallback>WZ</AvatarFallback>
32
      </Avatar>
33
      <AvatarGroupCount>+3</AvatarGroupCount>
34
    </AvatarGroup>
35
  );
36
}

Avatar Group with Icon

You can also use an icon inside <AvatarGroupCount>.

HRPRWZ

1
import {
2
  Avatar,
3
  AvatarFallback,
4
  AvatarGroup,
5
  AvatarGroupCount,
6
  AvatarImage,
7
} from "@/components/ui/pxl/avatar";
8

9
export default function AvatarGroupCountIconExample() {
10
  return (
11
    <AvatarGroup className="grayscale">
12
      <Avatar>
13
        <AvatarImage
14
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
15
          alt="@hero"
16
        />
17
        <AvatarFallback>HR</AvatarFallback>
18
      </Avatar>
19
      <Avatar>
20
        <AvatarImage
21
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/princess.png"
22
          alt="@princess"
23
        />
24
        <AvatarFallback>PR</AvatarFallback>
25
      </Avatar>
26
      <Avatar>
27
        <AvatarImage
28
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/wizard.png"
29
          alt="@wizard"
30
        />
31
        <AvatarFallback>WZ</AvatarFallback>
32
      </Avatar>
33
      <AvatarGroupCount>
34
        <svg
35
          xmlns="http://www.w3.org/2000/svg"
36
          fill="currentColor"
37
          viewBox="0 0 24 24"
38
        >
39
          <path d="M13 11h7v2h-7v7h-2v-7H4v-2h7V4h2v7Z" />
40
        </svg>
41
      </AvatarGroupCount>
42
    </AvatarGroup>
43
  );
44
}

Sizes

Use the size prop to change the size of the avatar.

IHSIHSIHSIHS

1
import {
2
  Avatar,
3
  AvatarFallback,
4
  AvatarImage,
5
} from "@/components/ui/pxl/avatar";
6

7
export default function SizesExample() {
8
  return (
9
    <div className="flex flex-wrap items-center gap-2 grayscale">
10
      <Avatar size="sm">
11
        <AvatarImage
12
          alt="@hero"
13
          className="bg-primary"
14
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
15
        />
16
        <AvatarFallback>IHS</AvatarFallback>
17
      </Avatar>
18
      <Avatar size="md">
19
        <AvatarImage
20
          alt="@hero"
21
          className="bg-primary"
22
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
23
        />
24
        <AvatarFallback>IHS</AvatarFallback>
25
      </Avatar>
26
      <Avatar size="lg">
27
        <AvatarImage
28
          alt="@hero"
29
          className="bg-primary"
30
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
31
        />
32
        <AvatarFallback>IHS</AvatarFallback>
33
      </Avatar>
34
      <Avatar size="xl">
35
        <AvatarImage
36
          alt="@hero"
37
          className="bg-primary"
38
          src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/portraits/hero.png"
39
        />
40
        <AvatarFallback>IHS</AvatarFallback>
41
      </Avatar>
42
    </div>
43
  );
44
}

API Reference

Avatar

The Avatar component is the root component that wraps the avatar image and fallback.

Prop	Type	Default
`size`	`"default" \| "sm" \| "lg"`	`"default"`
`className`	`string`	-

AvatarImage

The AvatarImage component displays the avatar image. It accepts all Base UI Avatar Image props.

Prop	Type	Default
`src`	`string`	-
`alt`	`string`	-
`className`	`string`	-

AvatarFallback

The AvatarFallback component displays a fallback when the image fails to load. It accepts all Base UI Avatar Fallback props.

Prop	Type	Default
`className`	`string`	-

AvatarBadge

The AvatarBadge component displays a badge indicator on the avatar, typically positioned at the bottom right.

Prop	Type	Default
`className`	`string`	-

AvatarGroup

The AvatarGroup component displays a group of avatars with overlapping styling.

Prop	Type	Default
`className`	`string`	-

AvatarGroupCount

The AvatarGroupCount component displays a count indicator in an avatar group, typically showing the number of additional avatars.

Prop	Type	Default
`className`	`string`	-

For more information about Base UI Avatar props, see the Base UI documentation.