Looking for documentation on gluestack-ui v2 with NativeWind? Refer to this link.
This is an illustration of a Themed Avatar component with default configuration.
size
borderRadius
<Avatar bgColor="$amber600" size="md" borderRadius="$full">
  <AvatarFallbackText>Sandeep Srivastava</AvatarFallbackText>
</Avatar>

API Reference

Import

To use this component in your project, include the following import statement in your file.
import {
  Avatar,
  AvatarBadge,
  AvatarFallbackText,
  AvatarImage,
} from "@gluestack-ui/themed"

Anatomy

IOS: It is highly recommended to use <AvatarFallbackText /> before <AvatarImage /> to avoid indexing issues in IOS.
The structure provided below can help you identify and understand an Avatar component's various parts.
export default () => (
  <AvatarGroup>
    <Avatar>
      <AvatarFallbackText />
      <AvatarImage />
      <AvatarBadge />
    </Avatar>
  </AvatarGroup>
)

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

Avatar

It inherits all the properties of React Native's View component.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_badge
Prop to style AvatarBadge Component
_text
Prop to style AvatarFallbackText Component

AvatarGroup

It also inherits all the properties of React Native's View component.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_avatar
Prop to style Avatar Component

AvatarImage

It inherits all the properties of React Native's Image component.

AvatarFallbackText

It inherits all the properties of React Native's Text component.

AvatarBadge

It inherits all the properties of React Native's View component.

Features

  • Returns a fallback to FallbackText if given an invalid image source.

Themed

The themed version of the component is a pre-styled version of the component, which allows you to quickly integrate the component into your project. The component's design and functionality are fully defined, allowing you to focus on the more important aspects of your project. To know more about Themed Library please visit this link.

Props

Avatar component is created using View component from react-native. It extends all the props supported by React Native View, utility props and the props mentioned below.

Avatar

Name
Value
Default
size
xs | sm | md | lg | xl | 2xl
md
Note: These props are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these props may not be available.

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Avatar with letters

An Avatar component with text displays a stylized representation of a user or entity alongside accompanying text, providing a visual and textual identification within a user interface.
<VStack space="2xl">
  <HStack space="md">
    <Avatar bgColor="$indigo600">
      <AvatarFallbackText>Ronald Richards</AvatarFallbackText>
      <AvatarBadge $dark-borderColor="$black" />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar bgColor="$orange600">
      <AvatarFallbackText>Arlene McCoy</AvatarFallbackText>
    </Avatar>
    <VStack>
      <Heading size="sm">Arlene McCoy</Heading>
      <Text size="sm">Marketing Coordinator</Text>
    </VStack>
  </HStack>
</VStack>

Avatar with Icon

An Avatar component with an icon combines a graphical symbol or icon with a user or entity representation, providing a visually appealing and easily recognizable identification within a user interface.
<VStack space="2xl">
  <HStack space="md">
    <Avatar bgColor="$indigo600">
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} color="white" size="lg" />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar bgColor="$pink600">
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} color="white" size="lg" />
    </Avatar>
    <VStack>
      <Heading size="sm">Kevin James</Heading>
      <Text size="sm">Web Designer</Text>
    </VStack>
  </HStack>
</VStack>

Avatar with Image

An Avatar component with an image incorporates a user or entity representation using a profile picture or image, adding a personalized touch and visual identification within a user interface.
<VStack space="2xl">
  <HStack space="md">
    <Avatar>
      <AvatarFallbackText>SS</AvatarFallbackText>
      <AvatarImage
        source={{
          uri: "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8dXNlcnxlbnwwfHwwfHw%3D&auto=format&fit=crop&w=800&q=60",
        }}
      />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar>
      <AvatarFallbackText>SS</AvatarFallbackText>
      <AvatarImage
        source={{
          uri: "https://images.unsplash.com/photo-1633332755192-727a05c4013d?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxzZWFyY2h8MXx8dXNlcnxlbnwwfHwwfHw%3D&auto=format&fit=crop&w=800&q=60",
        }}
      />
    </Avatar>
    <VStack>
      <Heading size="sm">Arlene McCoy</Heading>
      <Text size="sm">Marketing Coordinator</Text>
    </VStack>
  </HStack>
</VStack>

Avatar Group

The avatar group allows users to group avatars and display them in a horizontal or vertical row for better visual representation and functionality.
To reverse the order of avatars in case of multiple avatars use flexDirection="row" in <AvatarGroup>
function App() {
  const avatars = [
    {
      src: "https://example.com.jpg",
      alt: "Sandeep Srivastva",
      color: "$emerald600",
    },
    { src: "https://example.com.jpg", alt: "Arjun Kapoor", color: "$cyan600" },
    {
      src: "https://example.com.jpg",
      alt: "Ritik Sharma ",
      color: "$indigo600",
    },
    { src: "https://example.com.jpg", alt: "Akhil Sharma", color: "$gray600" },
    { src: "https://example.com.jpg", alt: "Rahul Sharma ", color: "$red400" },
  ]
  const extraAvatars = avatars.slice(3)
  const remainingCount = extraAvatars.length
  return (
    <AvatarGroup>
      {avatars.slice(0, 3).map((avatar, index) => {
        return (
          <Avatar
            key={index}
            size="lg"
            borderColor="$white"
            borderWidth="$2"
            bg={avatar.color}
            $dark-borderColor="$black"
          >
            <AvatarFallbackText>{avatar.alt}</AvatarFallbackText>
          </Avatar>
        )
      })}
      <Avatar
        size="lg"
        borderColor="$white"
        borderWidth="$2"
        bg="$gray600"
        $dark-borderColor="$black"
      >
        <AvatarFallbackText>{"+ " + remainingCount + ""}</AvatarFallbackText>
      </Avatar>
    </AvatarGroup>
  )
}

Avatar Group (Without Badge)

An Avatar Group component without badges organizes multiple avatars in a visually cohesive manner, offering a streamlined display of user or entity representations without additional visual indicators or badges within a user interface.
<AvatarGroup>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=687&q=80",
      }}
    />
  </Avatar>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1603415526960-f7e0328c63b1?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1470&q=80",
      }}
    />
  </Avatar>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1614289371518-722f2615943d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=687&q=80",
      }}
    />
  </Avatar>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1607746882042-944635dfe10e?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1470&q=80",
      }}
    />
  </Avatar>
</AvatarGroup>

Avatar Group (with Badge)

An Avatar Group component with badges presents a collection of avatars with accompanying badges, providing visual indicators or additional information associated with each user or entity representation within a user interface.
<AvatarGroup>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=687&q=80",
      }}
    />
    <AvatarBadge $dark-borderColor="$black" />
  </Avatar>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1603415526960-f7e0328c63b1?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1470&q=80",
      }}
    />
    <AvatarBadge $dark-borderColor="$black" />
  </Avatar>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1614289371518-722f2615943d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=687&q=80",
      }}
    />
    <AvatarBadge $dark-borderColor="$black" />
  </Avatar>
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://images.unsplash.com/photo-1607746882042-944635dfe10e?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1470&q=80",
      }}
    />
    <AvatarBadge $dark-borderColor="$black" />
  </Avatar>
</AvatarGroup>

Custom

A custom Avatar component with text allows for personalized user or entity representations by combining customized visuals, such as an image or icon, with accompanying text, providing a unique and identifiable presentation within a user interface.
<VStack space="2xl">
  <HStack space="md">
    <Avatar
      size="md"
      bgColor="$indigo300"
      borderColor="$indigo600"
      borderWidth={2}
    >
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} color="$indigo600" size="xl" />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar size="md" bgColor="$pink300" borderColor="$pink600" borderWidth={2}>
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} color="$pink600" size="xl" />
    </Avatar>
    <VStack>
      <Heading size="sm">Kevin James</Heading>
      <Text size="sm">Web Designer</Text>
    </VStack>
  </HStack>
</VStack>

Fallback

Fallback text is shown when the image fails to load, the image is not available or the provided image url is not correct.
<HStack space="md" h="100%" justifyContent="center" alignItems="center">
  <Avatar size="md">
    <AvatarFallbackText>John Doe</AvatarFallbackText>
    <AvatarImage
      source={{
        uri: "https://wrong-url",
      }}
    />
  </Avatar>
</HStack>

Unstyled

All the components in gluestack-ui are unstyled by default. To customize your UI using the extendedTheme, please refer to this link. The import names of components serve as keys to customize each component.

Spec Doc

Explore the comprehensive details of the Avatar in this document, including its implementation details, checklist, and potential future additions. Dive into the thought process behind the component and gain insights into its development journey.