Avatar

Used to represent a user with either a profile image, initials, or icon.

• View on Github

• View Core API

• View on Figma

Import

import { Avatar } from '@pluralsight/react'

This component is only compatible with React v18 and above and is a client component. This is due to the use of the Suspense tag and advanced preloading logic. If you are using an older version of React, we highly recommend you upgrade for both security and performance reasons.

Anatomy

1. Container
2. Image, initials, or icon

Usage

Static Avatar

function BasicAvatar() {
  return (
    <Grid cols="12" gap={16}>
      <GridItem col="span 2">
        <Avatar
          name="some person"
          src="https://source.unsplash.com/random/?face&fit=facearea&facepad=2&w=256&h=256&q=80"
        />
      </GridItem>

      <GridItem col="span 2">
        <Avatar name="some person" src="http://badURL" />
      </GridItem>

      <GridItem col="span 2">
        <Avatar />
      </GridItem>
    </Grid>
  )
}

Actionable Avatar

When an avatar is meant to be interactive, use the action sentiment.

function ActionableAvatar() {
  function handleAvatarClick() {
    // show user profile in sidebar
  }

  return (
    <div style={{ paddingTop: '1rem', paddingBottom: '1rem' }}>
      <Grid cols="12" gap={16}>
        <GridItem col="span 2">
          <a href="/" target="_blank">
            <Avatar
              name="some person"
              sentiment="action"
              src="https://source.unsplash.com/random/?face&fit=facearea&facepad=2&w=256&h=256&q=80"
            />
          </a>
        </GridItem>

        <GridItem col="span 2">
          <Button
            data-site-override="resetHeight"
            usage="text"
            onClick={handleAvatarClick}
          >
            <Avatar name="some person" sentiment="action" src="" />
          </Button>
        </GridItem>
      </Grid>
    </div>
  )
}

Sizes

To adjust the size, use the size prop. The default size is m.

function AvatarSizes() {
  const src =
    'https://source.unsplash.com/random/?face&fit=facearea&facepad=2&w=256&h=256&q=80'

  return (
    <Grid cols="12" gap={16} data-site-override="alignGridCenter">
      <GridItem col="span 1">
        <Avatar name="xtra small" size="xs" src={src} />
      </GridItem>

      <GridItem col="span 1">
        <Avatar name="small" size="s" src={src} />
      </GridItem>

      <GridItem col="span 2">
        <Avatar name="medium" size="m" src={src} />
      </GridItem>

      <GridItem col="span 2">
        <Avatar name="large" size="l" src={src} />
      </GridItem>

      <GridItem col="span 3">
        <Avatar name="xtra large" size="xl" src={src} />
      </GridItem>
    </Grid>
  )
}

Customizing

There are 3 ways to customize the Avatar component.

1. Unused Classes

Each component layer of the Avatar has a unused class name that can be utilized in your local CSS to customize the Avatar at any level.

1. pando-avatar: The container of the Avatar.
2. pando-avatar-image: The image element.
3. pando-avatar-label: The text element.
4. pando-avatar-icon: The icon element.

2. Passing a className prop

You can pass a className prop to the Avatar components to customize the Avatar at the container level. This is useful if your project uses CSS Modules or a CSS-in-JS library like Emotion.

import customStyles from './customStyles.module.css'

function CustomAvatar(props) {
  return (
    <Avatar
      className={customStyles.customAvatar}
      name={props.name}
      src={props.src}
    />
  )
}

3. Ejected Avatar

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Avatar however you prefer while keeping the accessibility behavior.

import {
  getAvatarProps,
  getAvatarImageProps,
  getAvatarLabelProps,
  getAvatarIconOptions,
} from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Placement

Do keep the original shape of the Avatar and clear from any portion being blocked.

Don't change the shape of the Avatar or block a portion of the component.

States

Do use the Image version as the preferred solution, then the Initials as a fallback version.

Don't use the Icon version unless it is a last resort.

Static/Action Scenarios

Do use the actionable Avatar when you need the Avatar to trigger an action.

Don't use the static Avatar when you need the Avatar to trigger an action.

API

Parameters

interface AvatarProps extends HTMLAttributes<HTMLImageElement> {
  name?: string
  size?: 'xs' | 's' | 'm' | 'l' | 'xl'
  src?: string
  sentiment?: 'action' | 'default'
}

1. Any props that can be passed to a div element.
2. name - The name of the user.
3. src - The URL of the image.
4. size - The size of the Avatar.
5. sentiment - The sentiment of the Avatar.

Size Mapping

{
  // Menu bars or tight areas where multiple users may be listed
  xs: '32px',

  // Reference user/author in meta data space or reference card
  s: '48px',

  // Single-page or focused experience to identify the author or user profile
  m: '80px',

  // Profile card as the primary image
  l: '120px',

  // Hero header or primary image in Profile page
  xl: '160px',
}

Accessibility

The Pando Avatar is fully accessible and screen-readable through the following features:

1. The alt attribute is added for the img element/version.
2. The aria-label attribute is added for the label element/version.
3. The aria-hidden attribute is added for the icon element/version.