Skip to main content

Avatar

Avatar displays a user or entity with an image, initials fallback, or placeholder icon.

Import​

import { Avatar } from "@tosui/react";

Basic Usage​

<Avatar src="https://i.pravatar.cc/150?img=1" name="John Doe" />

Sizes​

<HStack gap={4} align="center">
  <Avatar size="sm" name="John Doe" />
  <Avatar size="md" name="John Doe" />
  <Avatar size="lg" name="John Doe" />
  <Avatar size="xl" name="John Doe" />
</HStack>

Initials Fallback​

When no image is provided, Avatar shows initials from the name.

<HStack gap={4}>
  <Avatar name="John Doe" />
  <Avatar name="Jane Smith" />
  <Avatar name="Alice" />
  <Avatar name="Bob Builder" />
</HStack>

Placeholder​

When no name or image is provided, a placeholder icon is shown.

<Avatar />

Rounded Variants​

<HStack gap={4}>
  <Avatar rounded="full" name="John Doe" />
  <Avatar rounded="md" name="Jane Smith" />
</HStack>

Image Error Fallback​

If the image fails to load, Avatar falls back to initials.

<Avatar
  src="https://broken-url.example/image.jpg"
  name="John Doe"
/>
// Falls back to "JD" initials

Common Patterns​

Avatar with Name​

<HStack gap={3} align="center">
  <Avatar size="md" name="John Doe" />
  <VStack gap={0} align="flex-start">
    <Box fontWeight="medium">John Doe</Box>
    <Box fontSize="sm" color="foreground-muted">john@example.com</Box>
  </VStack>
</HStack>

Avatar Group​

<HStack gap={-2}>
  <Avatar name="Alice" size="md" />
  <Avatar name="Bob" size="md" />
  <Avatar name="Carol" size="md" />
  <Avatar name="Dan" size="md" />
</HStack>

Props Reference​

PropTypeDefaultDescription
srcstring-Image source URL
namestring-Name for initials fallback
size"sm" | "md" | "lg" | "xl""md"Avatar size
rounded"full" | "md""full"Border radius
altstringname or "Avatar"Alt text for image

Size Dimensions​

SizeDimensions
sm32px
md40px
lg48px
xl64px

TypeScript​

import { Avatar, type AvatarSize, type AvatarProps } from "@tosui/react";