MC Avatar
A component for displaying user profile images.
Overview
The mc-avatar family provides a polished avatar system for user identity and presence. Built on the @base-ui/react/avatar primitive, it supports image rendering, initials fallback, badge overlays, and grouped avatars with responsive sizing.
As a part of the MicroClub library, this component is designed for instant deployment into your codebase, giving you full ownership of its look and behavior.
Preview
Loading...
import { McAvatar, McAvatarBadge, McAvatarFallback, McAvatarGroup, McAvatarGroupCount, McAvatarImage,} from '@/registry/ui/mc-avatar';export default function AvatarDemo() { return ( <div className="flex flex-row flex-wrap gap-6 md:gap-12"> <McAvatar> <McAvatarImage src="https://github.com/Adel2411.png" alt="@Adel2411" /> <McAvatarFallback>CN</McAvatarFallback> </McAvatar> <McAvatar> <McAvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" /> <McAvatarFallback>ER</McAvatarFallback> <McAvatarBadge className="bg-green-600 dark:bg-green-800" /> </McAvatar> <McAvatarGroup className="grayscale"> <McAvatar> <McAvatarImage src="https://github.com/Adel2411.png" alt="@Adel2411" /> <McAvatarFallback>CN</McAvatarFallback> </McAvatar> <McAvatar> <McAvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" /> <McAvatarFallback>LR</McAvatarFallback> </McAvatar> <McAvatar> <McAvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" /> <McAvatarFallback>ER</McAvatarFallback> </McAvatar> <McAvatarGroupCount>+3</McAvatarGroupCount> </McAvatarGroup> </div> );}Add to Your Project
Deploy the mc-avatar directly to your components/ui directory:
npx mcoli-ui@latest add mc-avatar
pnpm dlx mcoli-ui@latest add mc-avatar
yarn dlx mcoli-ui@latest add mc-avatar
bunx mcoli-ui@latest add mc-avatar
Manual Setup
If you prefer manual control:
Install the core dependencies
npm install @base-ui/react
pnpm add @base-ui/react
yarn add @base-ui/react
bun add @base-ui/react
Copy the source code
'use client';import * as React from 'react';import { Avatar as AvatarPrimitive } from '@base-ui/react/avatar';import { cn } from '@/lib/utils';function McAvatar({ className, size = 'default', ...props}: AvatarPrimitive.Root.Props & { size?: 'default' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';}) { return ( <AvatarPrimitive.Root data-slot="avatar" data-size={size} className={cn( 'group/avatar relative flex size-8 shrink-0 rounded-full select-none ', ' data-[size=xs]:size-6 data-[size=sm]:size-8 data-[size=md]:size-10 data-[size=lg]:size-12 data-[size=xl]:size-14 data-[size=2xl]:size-16 dark:after:mix-blend-lighten', ' ring-1 ring-border ring-inset ', className )} {...props} /> );}function McAvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) { return ( <AvatarPrimitive.Image data-slot="avatar-image" className={cn('aspect-square size-full rounded-full object-cover ', className)} {...props} /> );}function McAvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props) { return ( <AvatarPrimitive.Fallback data-slot="avatar-fallback" className={cn( 'flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ', ' group-data-[size=xs]/avatar:text-xs group-data-[size=sm]/avatar:text-sm group-data-[size=md]/avatar:text-base group-data-[size=lg]/avatar:text-lg group-data-[size=xl]/avatar:text-xl group-data-[size=2xl]/avatar:text-2xl', className )} {...props} /> );}function McAvatarBadge({ className, ...props }: React.ComponentProps<'span'>) { return ( <span data-slot="avatar-badge" className={cn( 'absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground ring-2 ring-background select-none empty:bg-success not-empty:bg-transparent overflow-hidden', 'group-data-[size=xs]/avatar:size-1.5 group-data-[size=xs]/avatar:[&>svg]:hidden', 'group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden', 'group-data-[size=md]/avatar:size-2.5 group-data-[size=md]/avatar:[&>svg]:size-2', 'group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2', 'group-data-[size=xl]/avatar:size-3.5 group-data-[size=xl]/avatar:[&>svg]:size-2.5', 'group-data-[size=2xl]/avatar:size-4 group-data-[size=2xl]/avatar:[&>svg]:size-3', 'not-empty:group-data-[size=xs]/avatar:size-2.5 group-data-[size=xs]/avatar:[&>svg]:hidden', 'not-empty:group-data-[size=sm]/avatar:size-3 group-data-[size=sm]/avatar:[&>svg]:hidden', 'not-empty:group-data-[size=md]/avatar:size-3.5 group-data-[size=md]/avatar:[&>svg]:size-2.5', 'not-empty:group-data-[size=lg]/avatar:size-4 group-data-[size=lg]/avatar:[&>svg]:size-2.5', 'not-empty:group-data-[size=xl]/avatar:size-4.5 group-data-[size=xl]/avatar:[&>svg]:size-3', 'not-empty:group-data-[size=2xl]/avatar:size-5 group-data-[size=2xl]/avatar:[&>svg]:size-3.5', className )} {...props} /> );}function McAvatarGroup({ className, ...props }: React.ComponentProps<'div'>) { return ( <div data-slot="avatar-group" className={cn( 'group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background', className )} {...props} /> );}function McAvatarGroupCount({ className, ...props }: React.ComponentProps<'div'>) { return ( <div data-slot="avatar-group-count" className={cn( 'relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3', className )} {...props} /> );}export { McAvatar, McAvatarImage, McAvatarFallback, McAvatarGroup, McAvatarGroupCount, McAvatarBadge,};Adjust import paths
Ensure your @/lib/utils or equivalent classname helper is correctly imported.
Usage
import {
McAvatar,
McAvatarImage,
McAvatarFallback,
McAvatarBadge,
McAvatarGroup,
McAvatarGroupCount,
} from '@/components/ui/mc-avatar';
export default function Example() {
return (
<McAvatar>
<McAvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<McAvatarFallback>CN</McAvatarFallback>
</McAvatar>
);
}Examples
Size Variants
<McAvatar size="xs">
<McAvatarFallback>XS</McAvatarFallback>
</McAvatar>
<McAvatar size="md">
<McAvatarFallback>MD</McAvatarFallback>
</McAvatar>
<McAvatar size="2xl">
<McAvatarFallback>2XL</McAvatarFallback>
</McAvatar>Image + Fallback
Use McAvatarImage for the user photo and McAvatarFallback for initials or a placeholder when the image fails to load.
<McAvatar>
<McAvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<McAvatarFallback>CN</McAvatarFallback>
</McAvatar>Badge Overlay
McAvatarBadge is a small status or presence indicator that scales with the avatar size.
<McAvatar>
<McAvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
<McAvatarFallback>ER</McAvatarFallback>
<McAvatarBadge className="bg-green-600 dark:bg-green-800" />
</McAvatar>Avatar Groups
Group related avatars with McAvatarGroup. Use McAvatarGroupCount to represent extra members.
<McAvatarGroup>
<McAvatar>
<McAvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<McAvatarFallback>CN</McAvatarFallback>
</McAvatar>
<McAvatar>
<McAvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
<McAvatarFallback>LR</McAvatarFallback>
</McAvatar>
<McAvatarGroupCount>+3</McAvatarGroupCount>
</McAvatarGroup>API Reference
McAvatar Props
| Prop | Type | Default | Description |
|---|---|---|---|
size | "default" "xs" "sm" "md" "lg" "xl" "2xl" | "default" | Controls avatar dimensions and badge scaling |
className | string | undefined | Additional CSS classes for the root avatar wrapper |
children | ReactNode | undefined | Avatar slots like McAvatarImage, McAvatarFallback, McAvatarBadge |
McAvatarImage Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | undefined | Image source URL |
alt | string | undefined | Accessible alt text for the image |
className | string | undefined | Additional CSS classes for the image |
McAvatarFallback Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | undefined | Additional CSS classes for fallback view |
McAvatarBadge Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | undefined | Additional CSS classes for the badge |
McAvatarGroup Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | undefined | Additional CSS classes for the group |
McAvatarGroupCount Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | undefined | Additional CSS classes for the overflow count |