---
title: Avatar | UI
description: Use the Avatar Component as a graphical representation of a person through a profile picture or image, an icon, or a string with initials.
pageTitle: Avatar
pageDescription: Use the Avatar Component as a graphical representation of a person through a profile picture or image, an icon, or a string with initials.
showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="components/Media And Icons/Avatar" />

import { Avatar, HStack, VStack } from './Avatar';
import { transformedCode } from '../../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  Text,
} from '@gluestack/design-system';

import { styled } from '@dank-style/react';

import Wrapper from '../../Wrapper';

# Installation

This command copies the `Avatar` component to your project.

```jsx
npx install @gluestack-ui add avatar
```

## Import

```jsx
// import the component from your component folder
import { Avatar } from 'components';
```

````

<br />

# Basic

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
<Avatar size="md">
  <Avatar.FallbackText>AB</Avatar.FallbackText>
  <Avatar.Image
    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.Badge />
</Avatar>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        Avatar,
      },
      argsType: {},
    }}
  />
</AppProvider>
<br />

## Anatomy

The avatar component consists of the following parts:

```jsx
export default () => (
  <Avatar.Group>
    <Avatar>
      <Avatar.FallbackText>AB</Avatar.FallbackText>
      <Avatar.Image />
      <Avatar.Badge />
    </Avatar>
  </Avatar.Group>
);
````

## API Reference

### Avatar

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

### Avatar.Group

It also inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

### Avatar.Image

It inherits all the properties of React Native's [Image](https://reactnative.dev/docs/image#props) component.

### Avatar.FallbackText

It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text#props) component.

### Avatar.Badge

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

## Features

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

<br />
<br />

## Dependencies

- `@gluestack-ui/utils`

## Examples

### Avatar Group

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
<HStack
  space="md"
  h="100%"
  justifyContent="center"
  alignItems="center">
  <Avatar.Group>
    <Avatar size="$md">
      <Avatar.FallbackText>AB</Avatar.FallbackText>
      <Avatar.Image
        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.Badge />
    </Avatar>
    <Avatar size="$md">
      <Avatar.FallbackText>AB</Avatar.FallbackText>
      <Avatar.Image
        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.Badge />
    </Avatar>
    <Avatar size="$md">
      <Avatar.FallbackText>AB</Avatar.FallbackText>
      <Avatar.Image
        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.Badge />
    </Avatar>
    <Avatar size="$md">
      <Avatar.FallbackText>AB</Avatar.FallbackText>
      <Avatar.Image
        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.Badge />
    </Avatar>
  </Avatar.Group>
</HStack>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Avatar, Wrapper, HStack },
      argsType: {},
    }}
  />
</AppProvider>

<br />

### Avatar Sizes

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
<VStack space="md" alignItems="center" h="100%" justifyContent="center">
  {['xs', 'sm', 'md', 'lg', 'xl', '2xl'].map((size, index) => (
    <Avatar size={size} key={index}>
      <Avatar.FallbackText>AB</Avatar.FallbackText>
      <Avatar.Image
        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.Badge />
    </Avatar>
  ))}
</VStack>
    `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Avatar, Wrapper, VStack },
      argsType: {},
    }}
  />
</AppProvider>

<br />

# Advanced

## Customizing the Avatar

We have a function called `createAvatar` which can be used to create a custom avatar component. This function takes in a configuration object which contains the styled components that you want to use for the avatar. You can refer [dank.style](https://dank.style/) for more information on how to use styled components.

### Usage

```jsx
// import the styles
import {
  Root,
  Badge,
  Group,
  Image,
  FallbackText,
} from '../components/core/avatar/styled-components';

// import the createAvatar function
import { createAvatar } from '@gluestack-ui/avatar';

// Understanding the API
const Avatar = createAvatar({
  Root,
  Badge,
  Group,
  Image,
  FallbackText,
});

// Using the avatar component
export default () => (
  <Avatar.Group>
    <Avatar>
      <Avatar.FallbackText />
      <Avatar.Badge />
    </Avatar>
  </Avatar.Group>
);
```

Default styling of all these components can be found in the `components/core/avatar` file. For reference, you can view the [source code](https://github.com/gluestack/gluestack-ui/blob/development/example/storybook/src/components/Button/index.tsx) of the styled `Avatar` components.