Avatar

Avatar displays a user's profile image with graceful fallback to initials or an icon when the image fails to load. It supports multiple sizes, variants, and colors for various contexts.

This is an enhanced version of the Avatar from Radix Themes, built on Radix UI Avatar.

Playground

Installation

npm install @kushagradhawan/kookie-ui

Usage

import { Avatar, Flex } from '@kushagradhawan/kookie-ui';
 
export function MyAvatars() {
  return (
    <Flex gap="3">
      <Avatar src="/profile.jpg" fallback="JD" />
      <Avatar fallback="AB" />
      <Avatar fallback="CD" color="violet" />
    </Flex>
  );
}

Props

With Image

Display a user's profile image.

<Avatar
  src="https://images.unsplash.com/photo-1502823403499-6ccfcf4fb453"
  fallback="JD"
  size="4"
/>

Fallback

When no image is provided or it fails to load, the fallback content is displayed.

<Flex gap="3">
  <Avatar fallback="JD" />
  <Avatar fallback="AB" color="violet" />
  <Avatar fallback="CD" color="green" />
</Flex>

Sizes

Avatars support 12 sizes from compact (1) to large (12).

<Flex gap="3" align="center">
  <Avatar size="1" fallback="1" />
  <Avatar size="2" fallback="2" />
  <Avatar size="3" fallback="3" />
  <Avatar size="4" fallback="4" />
  <Avatar size="5" fallback="5" />
  <Avatar size="6" fallback="6" />
</Flex>

Variants

Control the fallback appearance with variants.

<Flex gap="3">
  <Avatar fallback="CL" variant="classic" />
  <Avatar fallback="SO" variant="solid" />
  <Avatar fallback="SF" variant="soft" />
  <Avatar fallback="SU" variant="surface" />
  <Avatar fallback="OL" variant="outline" />
</Flex>

Colors

Use colors to differentiate users or roles.

<Flex gap="3">
  <Avatar
    fallback="JD"
    color="blue"
  />
  <Avatar
    fallback="AB"
    color="green"
  />
  <Avatar
    fallback="CD"
    color="violet"
  />
  <Avatar
    fallback="EF"
    color="pink"
  />
  <Avatar
    fallback="GH"
    color="amber"
  />
</Flex>

Radius

Customize the border radius.

<Flex gap="3">
  <Avatar fallback="JD" radius="none" />
  <Avatar fallback="JD" radius="small" />
  <Avatar fallback="JD" radius="medium" />
  <Avatar fallback="JD" radius="large" />
  <Avatar fallback="JD" radius="full" />
</Flex>

Status

Add a status indicator dot to show presence or state.

<Flex gap="3">
  <Avatar fallback="JD" status="green" />
  <Avatar fallback="AB" status="amber" />
  <Avatar fallback="CD" status="gray" />
</Flex>

The status indicator scales automatically with the avatar size.

<Flex gap="3" align="center">
  <Avatar
    fallback="JD"
    size="3"
    status="green"
  />
  <Avatar
    fallback="AB"
    size="5"
    status="green"
  />
  <Avatar
    fallback="CD"
    size="7"
    status="green"
  />
</Flex>

Badge

Use the badge prop for custom indicator content like icons or notification counts.

<Flex gap="3">
  <Avatar
    fallback="JD"
    badge={<Badge size="1">3</Badge>}
  />
  <Avatar
    fallback="AB"
    badge={<HugeiconsIcon icon={CheckmarkCircle02Icon} />}
  />
</Flex>

Note: status and badge cannot be used together. If both are provided, badge takes precedence and a warning is logged in development.

Fit

Control how images are scaled within the avatar container. This is useful for logos or images that shouldn't be cropped.

<Flex gap="3">
  <Avatar
    src="/company-logo.png"
    fallback="CO"
    fit="cover"
  />
  <Avatar
    src="/company-logo.png"
    fallback="CO"
    fit="contain"
  />
</Flex>

• cover (default): Scales image to fill the container, may crop edges
• contain: Scales image to fit entirely within container, may leave empty space
• fill: Stretches image to fill container exactly, may distort
• scale-down: Like contain but never scales up beyond original size
• none: Image keeps original size

The fit prop also supports responsive values:

<Avatar
  src="/logo.png"
  fallback="LO"
  fit={{ initial: 'cover', md: 'contain' }}
/>

Enhancements

Kookie UI extends Radix Themes Avatar with practical improvements:

Extended Sizes

Size scale expanded from 9 to 12 values, with consistent radius-to-size mapping and two-letter fallback font sizes at every scale.

Additional Variants

Three new variants beyond Radix's solid and soft: classic provides a raised 3D surface appearance with shadow, surface adds a subtle bordered background, and outline renders a border-only fallback with no fill.

Material Support

material prop controls solid vs. translucent rendering. Translucent avatars use backdrop-filter for a frosted-glass effect and automatically blend with the background. Works across all variants.

Status Indicator

status prop renders a colored dot at the bottom-right corner that scales automatically with the avatar size. Accepts any accent color for presence or state indication.

Badge Slot

badge prop accepts arbitrary React content rendered at the bottom-right corner for notification counts, verification icons, or other indicators. Mutually exclusive with status; badge takes precedence if both are provided.

Image Fit Control

Responsive fit prop controls object-fit on the avatar image. Useful for logos or non-square images that shouldn't be cropped. Supports cover, contain, fill, scale-down, and none.

Interactive Avatar Support

When rendered as a button, a, or [role="button"] via asChild, avatars gain hover, active, focus, and disabled states with subtle image brightness/saturation filters. Each variant applies appropriate interactive colors. Disabled detection propagates from the child element automatically.

Changelog

Added

• Sizes 10, 11, 12 for larger avatar use cases
• classic, surface, and outline variants
• material prop for solid/translucent theme contexts
• status prop for colored presence indicators
• badge prop for custom indicator content
• fit prop with responsive support for image scaling control
• Interactive states for button/link usage via asChild
• Disabled state detection from child element props
• Image hover/active filters with dark mode awareness

Changed

• Border-radius scale tightened to match size number (size 1 uses radius-1, etc.)
• Two-letter fallback font sizes defined for all sizes (Radix only defined sizes 1-4)
• Soft variant uses solid colors (--accent-3) instead of alpha (--accent-a3) for better consistency
• Solid high-contrast fallback uses --gray-1 instead of --accent-1

Deprecated

• panelBackground prop in favor of material prop