For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/avatar.md.
Leaf UI
  • English

      • Avatar

      Display an avatar for a user, team or object.

      Sizes and shapes

      Small
      Medium
      Large · Square
      Unread indicator
      basic.tsx
      import { Avatar, Badge, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Small</Text>
        <Avatar size="sm">LF</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Medium</Text>
        <Avatar>LE</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Large · Square</Text>
        <Avatar size="lg" shape="square">
          UI
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Unread indicator</Text>
        <Badge dot>
          <Avatar alt="Unread messages">A</Avatar>
        </Badge>
      </Flex>
    </Flex>
  );
}

      Image avatars

      Circle image
      Square image
      image.tsx
      import { Avatar, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarImage() {
  const image = '../../avatar-portrait.svg';
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Circle image</Text>
        <Avatar src={image} alt="Alex" size="lg" />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Square image</Text>
        <Avatar src={image} alt="Alex" size={64} shape="square" imageProps={{ loading: 'lazy' }} />
      </Flex>
    </Flex>
  );
}

      Fallbacks and defaults

      Text fallback
      Default icon
      fallback.tsx
      import { Avatar, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarFallback() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Text fallback</Text>
        <Avatar src="data:image/png;base64,broken" alt="Failed image">
          LF
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Default icon</Text>
        <Avatar alt="Guest" />
      </Flex>
    </Flex>
  );
}

      Extended features

      extensions.tsx
      import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <AvatarGroup maxCount={3}>
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}

      Avatar API

      PropertyTypeDefaultDescription
      src / srcSetstring—Image source / responsive candidates
      altstringText or localized defaultAccessible name
      imagePropsOmit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'alt' | 'onError'>—Image attributes such as loading, sizes, crossOrigin and objectFit styles
      onError() => void—Image loading error callback
      size'sm' | 'md' | 'lg' | number'md'Preset size or pixel value
      shape'circle' | 'square''circle'Shape
      icon / childrenReactNode—Fallback icon / text

      Types

      Import these types to define props or prepare data.

      import type { AvatarProps } from '@ifhover/leaf-ui';

      Usage notes

      Failed images fall back to children, icon or the default avatar. Changing the source retries loading. Alt provides an accessible name without duplicate image announcements. Use imageProps.style to customize cropping.

      Extension types

      import type { AvatarGroupProps } from '@ifhover/leaf-ui';

      AvatarGroupProps API

      PropertyTypeDefaultDescription
      maxCountnumberInfinityMaximum selections or visible items
      size'sm' | 'md' | 'lg' | number—Size or spacing preset
      shape'circle' | 'square'—Crop shape
      maxContent(hiddenCount: number) => ReactNode—Custom overflow count content