Skip to main content

Avatar

The Avatar component is used to represent a user, and displays the profile picture, initials or a fallback icon.

Import#

Pearl UI exports 2 avatar-related components:

  1. Avatar: Used to represent a single user.
  2. AvatarGroup: A wrapper which stacks multiple Avatar components together and provides the ability to truncate the number of avatars that get shown.
import { Avatar, AvatarGroup } from "pearl-ui";

Usage#

// Displaying a local user image<Avatar src={require("<path-to-local-user-image>.jpeg")} />
// Displaying a user image from a remote source<Avatar src="https://pbs.twimg.com/profile_images/1419369145058041856/eshLFaDy_400x400.jpg" />

Avatar sizes#

Use the size prop to change the size of the avatar. You can set the value to the keys available in theme.components.Avatar["sizes"], which are "s", "m", "l", and "xl" in the default theme.

<Avatar  src="https://pbs.twimg.com/profile_images/1419369145058041856/eshLFaDy_400x400.jpg"  size="s"/>
<Avatar  src="https://pbs.twimg.com/profile_images/1419369145058041856/eshLFaDy_400x400.jpg"  size="m"/>
<Avatar  src="https://pbs.twimg.com/profile_images/1419369145058041856/eshLFaDy_400x400.jpg"  size="l"/>
<Avatar  src="https://pbs.twimg.com/profile_images/1419369145058041856/eshLFaDy_400x400.jpg"  size="xl"/>

Avatar Fallback#

Sometimes, the image you want to display doesn't exist or cannot be accessed due to network issues. In these cases, it is a good practice to show a replacement to the user as a fallback.

// Displays an fallback avatar with the initials of the user<Avatar name="Rohit Agrawal" />;
// Displays an image saying 'No Image Available' in case the source image doesn't exist<Avatar  src="https://4kwallpapers.com/imas/wallpapers/macos-big-sur-apple-layers-fluidic-colorful-wwdc-stock-2560x1440-1455.jpg"  fallbackSource={{    uri: "https://cdn.segmentnext.com/wp-content/themes/segmentnext/images/no-image-available.jpg",  }}/>;
// Displays a custom component with an error icon in case the source image doesn't existimport { Icon } from "pearl-ui";
<Avatar  backgroundColor="neutral.200"  fallbackComponent={    <Icon      iconFamily="FontAwesome"      iconName="user-circle"      color="neutral.600"      rawSize={55}    />  }/>;

If both the props are specified, the fallbackComponent prop takes higher precedence over fallbackSource.

Avatar Group#

In some cases, you might need to stack avatars as a group. This is where the AvatarGroup component comes in handy.

It expects a max prop to limit the amount of avatars to show, and shows a "+X" label (where X is the remaining avatars). It also provides a central place to control the size and variant of all the children Avatar components. It also expects a spacing prop to adjust the spacing between the avatars.

<AvatarGroup spacing="2xl" max={2} truncatedBackgroundColor="neutral.200">  <Avatar    name="Rohit Agrawal"    src="https://pbs.twimg.com/profile_images/1419369145058041856/eshLFaDy_400x400.jpg"  />  <Avatar    name="Rohit Agrawal"    src="https://avatars.githubusercontent.com/u/29514438?s=400&u=d194d5de8df93f55038130ccc66429f94f8f900f&v=4"  />  <Avatar    name="Rohit Agrawal"    src="https://instagram.fdel1-3.fna.fbcdn.net/v/t51.2885-19/s320x320/160616189_1075891466264003_198594308312142696_n.jpg?_nc_ht=instagram.fdel1-3.fna.fbcdn.net&_nc_cat=111&_nc_ohc=-URhWepekUsAX_wt_-J&edm=ABfd0MgBAAAA&ccb=7-4&oh=00_AT-caDqy7XqUUTkGv5_QytlFTxtdZ2wVhZDgB4vU3Jl2qQ&oe=61DF5972&_nc_sid=7bff83"  /></AvatarGroup>

Avatar Badges#

You can use Badge to add status badges or pressable badges to the avatar to show online/offline status, add action buttons, etc.

const OnlineAvatar = withBadge(undefined, {  placement: "bottomRight",  backgroundColor: "success.500",  size: "s",  minW: 15,  h: 15,  offset: 0,})(Avatar);
const OfflineAvatar = withBadge(undefined, {  placement: "bottomRight",  backgroundColor: "danger.500",  size: "s",  minW: 15,  h: 15,  offset: 0,})(Avatar);
const AvatarWithEditButton = withBadge(  <Icon iconFamily="Ionicons" iconName="pencil" size="s" color="white" />,  {    placement: "bottomRight",    size: "m",    onPress: () => {      console.log("PRESSED!");    },  })(Avatar);

Changing the initials logic#

Avatar optionally expects a getInitials prop that lets you control how the user's initials should be computed.

const firstNameTwoLetters = (name: string) => `${name[0]}${name[1]}`.toUpperCase()
<Avatar name="Rohit Agrawal" getInitials={firstNameTwoLetters} />;

Override Style#

The Avatar component also supports a variety of style props which can be used to override the pre-defined component style in the theme. Manual style props passed into the component have a higher precedance than the default component config.

<Avatar mt="xl" borderRadius="m" />

Example#

Accessibility#

  • Avatar has the role of image.

Avatar Props#

Supported style props#

Avatar composes the Image component, you can pass all Image props to it.

Additional props#

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.Avatar["sizes"]"m"The size of the avatar.
variantfalsePearlTheme.components.Avatar["variants"]The variant of the avatar.
srcfalsestring | numberThe source of the Avatar image. This can be a url, or a local image.
namefalsestringThe name of the person in the avatar. If 'src' is not loaded or is missing, the 'name' will be used to create the initials.
getInitialsfalse(name: string): stringTakes the first letters of the nameA method to specify how initials are generated from a user's name.

AvatarGroup Props#

Supported style props#

AvatarGroup composes the Box component, you can pass all Box props to it.

Additional props#

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.Avatar["sizes"]"m"The size of all the children avatars in the group..
variantfalsePearlTheme.components.Avatar["variants"]The variant of all the children avatars in the group.
spacingfalsePearlTheme["spacing"]The spacing between the avatars.
truncatedBackgroundColorfalsePearlTheme["palette"]The background color of the circle which shows the "+X" label of remaining avatars.
maxfalsenumberTakes the first letters of the nameMaximum number of avatars to show. It'll truncate the avatars and show a "+X" label (where X is the remaining avatars).

Default component Config#

export default {  parts: ["root", "text"],  baseStyle: {    root: {      borderRadius: "full",      borderWidth: 2,      borderColor: {        light: "neutral.50",        dark: "neutral.800",      },    },  },  sizes: {    s: {      root: {        width: 40,        height: 40,      },      text: {        variant: "caption",      },    },    m: {      root: {        width: 55,        height: 55,      },      text: {        variant: "p1",        fontSize: "m",        lineHeight: "3xl",      },    },    l: {      root: {        width: 70,        height: 70,      },      text: {        variant: "p1",        fontSize: "m",        lineHeight: "3xl",      },    },    xl: {      root: {        width: 85,        height: 85,      },      text: {        variant: "p1",        fontSize: "4xl",        lineHeight: "8xl",      },    },  },  defaults: {    size: "m",  },};