Avatar

free

Avatar gives people, teams, and objects a compact visual identity across dense UI.

@floating-ui/reactmotion

Preview

Dark

Alice Smith

@alicesmith

import Avatar from '@/components/ui/Avatar';

export default function UsageDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-4">
      <div className="flex items-center gap-2">
        <Avatar src="/img/avatars/thumb-1.jpg" alt="Alice Smith" />
        <div className="min-w-0">
          <div className="font-medium text-foreground">Alice Smith</div>
          <div className="text-sm text-muted-foreground">@alicesmith</div>
        </div>
      </div>
    </div>
  );
}

Installation

Add this component with the NateUI CLI.

npx nateui@latest add Avatar

Examples

Types

Preview

Dark

import { PiUser } from 'react-icons/pi'
import Avatar from '@/components/ui/Avatar';

export default function TypesDemo() {
  return (
    <div className="inline-flex flex-wrap items-center justify-center gap-4">
      <Avatar className="bg-palette-blue-soft text-palette-blue-soft-foreground border-0">
        NU
      </Avatar>
      <Avatar icon={<PiUser />} />
      <Avatar src="/img/avatars/thumb-4.jpg" alt="Maya Chen" />
    </div>
  );
}

Sizes

Preview

Dark

import { PiUser } from 'react-icons/pi'
import Avatar from '@/components/ui/Avatar';

export default function SizeDemo() {
  return (
    <div className="inline-flex flex-wrap items-center justify-center gap-4">
      <Avatar size="sm" icon={<PiUser />} />
      <Avatar size="md" icon={<PiUser />} />
      <Avatar size="lg" icon={<PiUser />} />
      <Avatar size={64} icon={<PiUser />} />
    </div>
  );
}

Shapes

Preview

Dark

import Avatar from '@/components/ui/Avatar';

export default function ShapeDemo() {
  return (
    <div className="inline-flex flex-wrap items-center justify-center gap-4">
      <Avatar shape="square" src="/img/avatars/thumb-5.jpg" alt="Square avatar" />
      <Avatar shape="round" src="/img/avatars/thumb-6.jpg" alt="Rounded avatar" />
      <Avatar shape="circle" src="/img/avatars/thumb-7.jpg" alt="Circle avatar" />
    </div>
  );
}

Colors

Preview

Dark

NUJSPMQA

import Avatar from '@/components/ui/Avatar';

const colors = [
  {
    label: 'NU',
    className: 'border-0 bg-palette-blue-soft text-palette-blue-soft-foreground',
  },
  {
    label: 'JS',
    className: 'border-0  bg-palette-emerald-soft text-palette-emerald-soft-foreground',
  },
  {
    label: 'PM',
    className: 'border-0 bg-palette-purple-soft text-palette-purple-soft-foreground',
  },
  {
    label: 'QA',
    className: 'border-0 bg-palette-rose-soft text-palette-rose-soft-foreground',
  },
];

export default function ColorDemo() {
  return (
    <div className="inline-flex flex-wrap items-center justify-center gap-4">
      {colors.map((color) => (
        <Avatar key={color.label} className={color.className}>
          {color.label}
        </Avatar>
      ))}
    </div>
  );
}

Status

Preview

Dark

import Avatar from '@/components/ui/Avatar';
import Badge from '@/components/ui/Badge';

const users = [
  {
    name: 'Ivy Tan',
    image: '/img/avatars/thumb-8.jpg',
    statusClass: 'bg-success',
  },
  {
    name: 'Liam Wong',
    image: '/img/avatars/thumb-9.jpg',
    statusClass: 'bg-warning',
  },
  {
    name: 'Nora Lee',
    image: '/img/avatars/thumb-10.jpg',
    statusClass: 'bg-destructive',
  },
];

export default function StatusDemo() {
  return (
    <div className="inline-flex flex-wrap items-center justify-center gap-4">
      {users.map((user) => (
        <Badge key={user.name} overlap="circle" innerClass={user.statusClass}>
          <Avatar src={user.image} alt={user.name} />
        </Badge>
      ))}
    </div>
  );
}

Group

Preview

Dark

import Avatar from '@/components/ui/Avatar';

const members = [
  {
    name: 'Ava Chen',
    image: '/img/avatars/thumb-11.jpg',
  },
  {
    name: 'Daniel Kim',
    image: '/img/avatars/thumb-12.jpg',
  },
  {
    name: 'Mira Patel',
    image: '/img/avatars/thumb-13.jpg',
  },
  {
    name: 'Omar Ali',
    image: '/img/avatars/thumb-14.jpg',
  },
  {
    name: 'Sara Lim',
    image: '/img/avatars/thumb-15.jpg',
  },
  {
    name: 'Theo Park',
    image: '/img/avatars/thumb-16.jpg',
  },
];

export default function GroupDemo() {
  return (
    <Avatar.Group
      chained
      maxCount={4}
      omittedAvatarProps={{ shape: 'circle' }}
    >
      {members.map((member) => (
        <Avatar
          key={member.name}
          src={member.image}
          alt={member.name}
        />
      ))}
    </Avatar.Group>
  );
}

API

Avatar accepts the props below plus native props for the root span.

Avatar

Prop	Description	Type	Default
`alt`	Alternate text passed to the rendered image when `src` is set.	`string`	-
`children`	Text fallback shown when neither `src` nor `icon` is provided.	`ReactNode`	-
`className`	Class names applied to the root avatar.	`string`	-
`icon`	Icon content shown when no image source is provided.	`ReactNode`	-
`onClick`	Click handler for interactive avatar usage.	`() => void`	-
`ref`	Ref forwarded to the root `span`.	`Ref<HTMLSpanElement>`	-
`shape`	Avatar corner treatment.	`AvatarShape`	`'circle'`
`size`	Preset size or numeric pixel size.	`AvatarSize`	`'md'`
`src`	Image URL rendered inside the avatar.	`string`	-
`srcSet`	Responsive image source set passed to the rendered image.	`string`	-
`...nativeSpanProps`	Native props for the root `span`.	`NativeAvatarSpanProps`	-

Avatar.Group

Prop	Description	Type	Default
`chained`	Overlaps child avatars into a chained stack.	`boolean`	`false`
`children`	Avatar elements rendered in the group.	`ReactNode`	-
`className`	Class names applied to the group wrapper.	`string`	-
`maxCount`	Maximum number of child avatars to show before rendering the overflow avatar.	`number`	`4`
`omittedAvatarContent`	Custom content for the overflow avatar.	`string \| ReactNode`	`'+N'`
`omittedAvatarProps`	Avatar props applied to the generated overflow avatar.	`Avatar props object`	-
`omittedAvatarTooltip`	Wraps the overflow avatar in a tooltip.	`boolean`	`false`
`omittedAvatarTooltipProps`	Tooltip props applied to the overflow tooltip, excluding `title`.	`AvatarTooltipProps`	-
`onOmittedAvatarClick`	Click handler for the overflow avatar.	`() => void`	-
`...nativeDivProps`	Native props for the group wrapper `div`.	`NativeAvatarGroupDivProps`	-

Types

type AvatarShape = 'round' | 'circle' | 'square';
type AvatarSize = 'sm' | 'md' | 'lg' | number;
type NativeAvatarSpanProps = ComponentProps<'span'>;
type AvatarTooltipProps = Omit<TooltipProps, 'title'>;
type NativeAvatarGroupDivProps = ComponentProps<'div'>;