Avatar

Import

import { Avatar } from "@thenamespace/uikit";

Usage

import {Avatar} from "@thenamespace/uikit";

export function Basic() {
  return (
    <div className="flex items-center gap-4">

Anatomy

Import the Avatar component and access all parts using dot notation.

import { Avatar } from "@thenamespace/uikit";

export default () => (
  <Avatar>
    <Avatar.Image />
    <Avatar.Fallback />
  </Avatar>
);

Sizes

import {Avatar} from "@thenamespace/uikit";

export function Sizes() {
  return (
    <div className="flex items-center gap-4">

Colors

import {Avatar} from "@thenamespace/uikit";

export function Colors() {
  return (
    <div className="flex items-center gap-4">

Variants

import { Avatar, Separator } from "@thenamespace/uikit";
import { UserIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";

export function Variants() {
  const colors = ["accent", "default", "success", "warning", "danger"] as const;

Fallback Content

import { Avatar } from "@thenamespace/uikit";
import { UserIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";

export function Fallback() {
  return (

Avatar Group

import {Avatar} from "@thenamespace/uikit";

const users = [
  {
    id: 1,

Custom Styles

import {Avatar} from "@thenamespace/uikit";

export function CustomStyles() {
  return (
    <div className="flex items-center gap-4">

Custom Image Component

Use asChild on Avatar.Image to compose with a custom image component. This example uses Next.js Image for optimized loading. Pass src on Avatar.Image so it can track the loading state and show the fallback until the image is ready.

import Image from "next/image";

import { Avatar } from "@thenamespace/uikit";

const SRC = "/assets/avatars/blue.jpg";

Styling

Passing Tailwind CSS classes

import { Avatar } from "@thenamespace/uikit";

function CustomAvatar() {
  return (
    <Avatar className="size-20">
      <Avatar.Image src="..." alt="..." />
      <Avatar.Fallback>XL</Avatar.Fallback>
    </Avatar>
  );
}

Customizing the component classes

To customize the Avatar component classes, you can use the @layer components directive.

Learn more.

@layer components {
  .avatar {
    @apply size-16 border-2 border-primary;
  }

  .avatar__fallback {
    @apply bg-gradient-to-br from-purple-500 to-pink-500;
  }
}

Namespace UIKit follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Avatar component uses these CSS classes:

Base Classes

• .avatar - Base container with default size (size-10)
• .avatar__image - Image element with aspect-square sizing
• .avatar__fallback - Fallback container with centered content

Size Modifiers

• .avatar--sm - Small avatar (size-8)
• .avatar--md - Medium avatar (default, no additional styles)
• .avatar--lg - Large avatar (size-12)

Variant Modifiers

• .avatar--soft - Soft variant with lighter background

Color Modifiers

• .avatar__fallback--default - Default text color
• .avatar__fallback--accent - Accent text color
• .avatar__fallback--success - Success text color
• .avatar__fallback--warning - Warning text color
• .avatar__fallback--danger - Danger text color

API Reference

Avatar Props

Avatar.Image Props

Avatar.Fallback Props