Avatar

Enhance UI engagement with a versatile element showing user profiles via pictures, initials, or icons

Installation

API Reference

Examples

Important Note

This is the documentation for gluestack-ui v2 (beta). For @gluestack-ui/themed (stable) documentation, refer to gluestack-ui v1.

This is an illustration of Avatar component.

size

<Avatar size="md">
  <AvatarFallbackText>Jane 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 />
</Avatar>

Installation

CLI

Manual

Run the following command:

npx gluestack-ui add avatar

Step 1: Install the following dependencies:

npm i @gluestack-ui/avatar

Step 2: Copy and paste the following code into your project.

"use client"
import React from "react"
import { createAvatar } from "@gluestack-ui/avatar"

import { View, Text, Image, Platform } from "react-native"

import { tva } from "@gluestack-ui/nativewind-utils/tva"
import {
  withStyleContext,
  useStyleContext,
} from "@gluestack-ui/nativewind-utils/withStyleContext"
import { cssInterop } from "nativewind"
const SCOPE = "AVATAR"
import type { VariantProps } from "@gluestack-ui/nativewind-utils"

const UIAvatar = createAvatar({
  Root: withStyleContext(View, SCOPE),
  Badge: View,
  Group: View,
  Image: Image,
  FallbackText: Text,
})

cssInterop(UIAvatar, { className: "style" })
cssInterop(UIAvatar.Badge, { className: "style" })
cssInterop(UIAvatar.Group, { className: "style" })
cssInterop(UIAvatar.Image, { className: "style" })
cssInterop(UIAvatar.FallbackText, { className: "style" })

const avatarStyle = tva({
  base: "rounded-full justify-center items-center relative bg-primary-600 group-[.avatar-group]/avatar-group:-ml-2.5",
  variants: {
    size: {
      xs: "w-6 h-6",
      sm: "w-8 h-8",
      md: "w-12 h-12",
      lg: "w-16 h-16",
      xl: "w-24 h-24",
      "2xl": "w-32 h-32",
    },
  },
})

const avatarFallbackTextStyle = tva({
  base: "text-typography-0 font-semibold overflow-hidden text-transform:uppercase web:cursor-default",

  parentVariants: {
    size: {
      xs: "text-2xs",
      sm: "text-xs",
      md: "text-base",
      lg: "text-xl",
      xl: "text-3xl",
      "2xl": "text-5xl",
    },
  },
})

const avatarGroupStyle = tva({
  base: "group/avatar-group flex-row-reverse relative avatar-group",
})

const avatarBadgeStyle = tva({
  base: "w-5 h-5 bg-success-500 rounded-full absolute right-0 bottom-0 border-background-0 border-2",
  parentVariants: {
    size: {
      xs: "w-2 h-2",
      sm: "w-2 h-2",
      md: "w-3 h-3",
      lg: "w-4 h-4",
      xl: "w-6 h-6",
      "2xl": "w-8 h-8",
    },
  },
})

const avatarImageStyle = tva({
  base: "h-full w-full rounded-full absolute",
})

type IAvatarProps = Omit<
  React.ComponentPropsWithoutRef<typeof UIAvatar>,
  "context"
> &
  VariantProps<typeof avatarStyle>

export const Avatar = React.forwardRef<
  React.ElementRef<typeof UIAvatar>,
  IAvatarProps
>(({ className, size = "md", ...props }, ref) => {
  return (
    <UIAvatar
      ref={ref}
      {...props}
      className={avatarStyle({ size, class: className })}
      context={{ size }}
    />
  )
})

type IAvatarBadgeProps = React.ComponentPropsWithoutRef<typeof UIAvatar.Badge> &
  VariantProps<typeof avatarBadgeStyle>

export const AvatarBadge = React.forwardRef<
  React.ElementRef<typeof UIAvatar.Badge>,
  IAvatarBadgeProps
>(({ className, size, ...props }, ref) => {
  const { size: parentSize } = useStyleContext(SCOPE)

  return (
    <UIAvatar.Badge
      ref={ref}
      {...props}
      className={avatarBadgeStyle({
        parentVariants: {
          size: parentSize,
        },
        size,
        class: className,
      })}
    />
  )
})

type IAvatarFallbackTextProps = React.ComponentPropsWithoutRef<
  typeof UIAvatar.FallbackText
> &
  VariantProps<typeof avatarFallbackTextStyle>
export const AvatarFallbackText = React.forwardRef<
  React.ElementRef<typeof UIAvatar.FallbackText>,
  IAvatarFallbackTextProps
>(({ className, size, ...props }, ref) => {
  const { size: parentSize } = useStyleContext(SCOPE)

  return (
    <UIAvatar.FallbackText
      ref={ref}
      {...props}
      className={avatarFallbackTextStyle({
        parentVariants: {
          size: parentSize,
        },
        size,
        class: className,
      })}
    />
  )
})

type IAvatarImageProps = React.ComponentPropsWithoutRef<typeof UIAvatar.Image> &
  VariantProps<typeof avatarImageStyle>

export const AvatarImage = React.forwardRef<
  React.ElementRef<typeof UIAvatar.Image>,
  IAvatarImageProps
>(({ className, ...props }, ref) => {
  return (
    <UIAvatar.Image
      ref={ref}
      {...props}
      className={avatarImageStyle({
        class: className,
      })}
      // @ts-ignore
      style={
        Platform.OS === "web"
          ? { height: "revert-layer", width: "revert-layer" }
          : undefined
      }
    />
  )
})

type IAvatarGroupProps = React.ComponentPropsWithoutRef<typeof UIAvatar.Group> &
  VariantProps<typeof avatarGroupStyle>

export const AvatarGroup = React.forwardRef<
  React.ElementRef<typeof UIAvatar.Group>,
  IAvatarGroupProps
>(({ className, ...props }, ref) => {
  return (
    <UIAvatar.Group
      ref={ref}
      {...props}
      className={avatarGroupStyle({
        class: className,
      })}
    />
  )
})

Step 3: Update the import paths to match your project setup.

API Reference

To use this component in your project, include the following import statement in your file.

import {
  Avatar,
  AvatarBadge,
  AvatarFallbackText,
  AvatarImage,
} from "@/components/ui/avatar"

Important Note

IOS: It is highly recommended to use <AvatarFallbackText /> before <AvatarImage /> to avoid indexing issues in IOS.

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.

AvatarGroup

It also inherits all the properties of React Native's View 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.

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

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 className="bg-indigo-600">
      <AvatarFallbackText className="text-white">
        Ronald Richards
      </AvatarFallbackText>
      <AvatarBadge />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar className="bg-orange-600">
      <AvatarFallbackText className="text-white">
        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 className="bg-indigo-600">
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} size="lg" className="stroke-white" />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar className="bg-pink-600">
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} size="lg" className="stroke-white" />
    </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",
        }}
      />
      <AvatarBadge />
    </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.

Important Note

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: "bg-emerald-600",
    },
    {
      src: "https://example.com.jpg",
      alt: "Arjun Kapoor",
      color: "bg-cyan-600",
    },
    {
      src: "https://example.com.jpg",
      alt: "Ritik Sharma ",
      color: "bg-indigo-600",
    },
    {
      src: "https://example.com.jpg",
      alt: "Akhil Sharma",
      color: "bg-gray-600",
    },
    {
      src: "https://example.com.jpg",
      alt: "Rahul Sharma ",
      color: "bg-red-400",
    },
  ]
  const extraAvatars = avatars.slice(3)
  const remainingCount = extraAvatars.length
  return (
    <AvatarGroup>
      {avatars.slice(0, 3).map((avatar, index) => {
        return (
          <Avatar
            key={index}
            size="lg"
            className={"border-2 border-outline-0 " + avatar.color}
          >
            <AvatarFallbackText className="text-white">
              {avatar.alt}
            </AvatarFallbackText>
          </Avatar>
        )
      })}
      <Avatar size="lg">
        <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 />
  </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 />
  </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 />
  </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 />
  </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" className="bg-indigo-300 border-2 border-indigo-600">
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} size="xl" className="text-indigo-600" />
    </Avatar>
    <VStack>
      <Heading size="sm">Ronald Richards</Heading>
      <Text size="sm">Nursing Assistant</Text>
    </VStack>
  </HStack>
  <HStack space="md">
    <Avatar size="md" className="bg-pink-300 border-2 border-pink-600">
      {/* User is imported from 'lucide-react-native' */}
      <Icon as={User} size="xl" className="text-pink-600" />
    </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>