Avatar

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

Open in Storybook

Import

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

Basic usage

Preview

Code

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

Sizes

Preview

JD

JD

JD

JD

Code

<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.

Preview

JD

JS

A

BB

Code

<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.

Preview

Code

<Avatar />

Rounded variants

Preview

JD

JS

Code

<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

Preview

JD

John Doe

john@example.com

Code

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

Avatar group

Preview

A

B

C

D

Code

<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

Prop	Type	Default	Description
src	string	-	Image source URL
name	string	-	Name for initials fallback
size	"sm" | "md" | "lg" | "xl"	"md"	Avatar size
rounded	"full" | "md"	"full"	Border radius
alt	string	name or "Avatar"	Alt text for image
className	string	-	Additional CSS class

Size dimensions

Size	Dimensions
sm	32px
md	40px
lg	48px
xl	64px

TypeScript

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