Avatar

Avatar is a visual representation of a user's profile and identity.

Interaction Modes

Scanning

Selecting

Sources

Github

Storybook

Install

yarn add @workday/canvas-kit-react

Component Type

Indicator

Platform

Web

Component

Sana Canvas

Delivery Channels

Web, Web Mobile

Version

16.1.7

Experience Surfaces

Page Body Inline

Component Type

Indicator

Platform

Web

Component

Sana Canvas

Delivery Channels

Web, Web Mobile

Version

16.1.7

Experience Surfaces

Page Body Inline

Anatomy

Background: A randomly selected fill color for the initial-based variant.
Initials: The first letters of a user’s first and last names in a darker gradient of fill color.
Image: A user-uploaded image of themselves.

Usage Guidance

When to Use

Use Avatars to provide a user with a stronger identity or when an access point into their profile provides reasonable benefit.

When to Use Something Else

If the data is not a user, and a symbolic representation is needed, use an icon component instead.

Avatars vary on the basis of version, sizing, background, and default color.

Version

Avatars default to their initial-based version unless a user manually uploads a profile photo. The lettering inside the Avatar is based on the two letter English initials of the Western equivalent of a user name.

Sizing

Avatars should feel appropriately sized based on their importance and nearby content. They vary on a scale from XXS to XXL to accommodate an array of different possible use cases:

XXS: 24 x 24. Please note that it is recommended to use a larger size than XXS for all uses outside of pills.

XS: 32 x 32
S: 40 x 40
M: 48 x 48
L: 72 x 72
XL: 96 x 96
XXL: 120 x 120

Regardless of Avatar sizing, all tap targets are 48x48 or larger.

Color

Initial-based avatars are randomly assigned a gender neutral and contrast friendly color on a per-user basis.

Examples

Basic Example

The most basic usage requires only a name prop. The component automatically extracts and displays the initials. If you want to display a different set of initials, you can use the preferredInitials prop.

import {Avatar} from '@workday/canvas-kit-react/avatar';

export default () => {
  return <Avatar name="John Doe" />;
};

Image Avatar

You can display a profile image by providing the url prop.

Note: The url and the name prop is required for the image avatar. The name is used for the alt attribute on the image.

Image Fallback Behavior

The Avatar component includes intelligent fallback handling:

While the image loads, the user’s initials are displayed using the name prop
If the image fails to load, initials remain visible
The name prop serves as both the alt text and fallback content

import {Avatar} from '@workday/canvas-kit-react/avatar';

export default () => {
  return (
    <Avatar
      name="Happy Doggo"
      url={'https://picsum.photos/id/237/300/200'}
      objectFit="cover"
      size="medium"
    />
  );
};

Sizes

The Avatar component supports the following sizes:

extraExtraSmall is 24px x 24px
extraSmall is 32px x 32px
small is 40px x 40px
medium is 48px x 48px
large is 72px x 72px
extraLarge is 96px x 96px
extraExtraLarge is 120px x 120px

import {Avatar} from '@workday/canvas-kit-react/avatar';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const containerStyles = createStyles({
  display: 'inline-flex',
  gap: system.gap.sm,
});

export default () => {
  return (
    <div className={containerStyles}>
      <Avatar name="John Doe" size="extraExtraSmall" />
      <Avatar name="Logan McNeil" size="extraSmall" />
      <Avatar name="Wonder Woman" size="small" />
      <Avatar name="Iron Man" size="medium" />
      <Avatar name="Peter Parker" size="large" />
      <Avatar name="Bruce Banner" size="extraLarge" />
      <Avatar name="Elektra" size="extraExtraLarge" />
    </div>
  );
};

Variants

Choose from four predefined color schemes:

import {Avatar} from '@workday/canvas-kit-react/avatar';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const containerStyles = createStyles({
  display: 'inline-flex',
  gap: system.gap.sm,
});

export default () => {
  return (
    <div className={containerStyles}>
      <Avatar name="John Doe" variant="blue" />
      <Avatar name="Logan McNeil" variant="amber" />
      <Avatar name="Wonder Woman" variant="teal" />
      <Avatar name="Elektra" variant="purple" />
      <Avatar name="Mary Jane" variant="magenta" />
      <Avatar name="Green Arrow" variant="green" />
    </div>
  );
};

Advanced Custom Component

For complete control over styling and behavior, use the BaseAvatar component:

import {BaseAvatar} from '@workday/canvas-kit-react/avatar';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {base} from '@workday/canvas-tokens-web';

const customStyles = createStyles({
  cursor: 'pointer',
  backgroundColor: base.magenta300,
  color: base.magenta700,
  borderRadius: '50%',
  border: 'none',
  padding: '0',
  margin: '0',
  display: 'flex',
  alignItems: 'center',
  span: {
    cursor: 'pointer',
  },
});

export default () => {
  return (
    <BaseAvatar
      size={px2rem(56)}
      cs={customStyles}
      as="button"
      onClick={() => console.log('clicked')}
    >
      <BaseAvatar.Name name="John Doe Jane" />
    </BaseAvatar>
  );
};

Accessibility

If the Avatar is purely decorative, you can set the isDecorative prop to true to prevent the name prop from being forwarded to the alt attribute of the image.

Nicholas Smith

import {Avatar} from '@workday/canvas-kit-react/avatar';
import {Text} from '@workday/canvas-kit-react/text';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

// @ts-ignore
import nicholasAvatar from './nicholas-avatar.jpg';

const containerStyles = createStyles({
  display: 'inline-flex',
  gap: system.gap.sm,
  alignItems: 'center',
});
export default () => {
  return (
    <div className={containerStyles}>
      <Avatar
        name="Nicholas Smith"
        isDecorative
        url={nicholasAvatar}
        objectFit="cover"
        size="small"
      />
      <Text>Nicholas Smith</Text>
    </div>
  );
};

Component API

Avatar

Props

Props extend from div. Changing the as prop will change the element interface.

Name	Type	Description	Default
`url`	`string`	The URL of the user's photo. For best fit, use square images.
`objectFit`	`Property.ObjectFit`	An objectFit property that can customize how to resize your image to fit its container.	`'contain'`
`isDecorative`	`boolean`	If true, the Avatar won't forward the `name` prop to the `alt` attribute of the image. This is useful when the Avatar is purely decorative and is rendered next to a name or text.
`children`	`ReactNode`	Children of the BaseAvatar.
`variant`	`'blue' \| 'amber' \| 'teal' \| 'purple' \| 'magenta' \| 'green'`	The variant of the Avatar.	`'blue'`
`size`	`'extraExtraSmall' \| 'extraSmall' \| 'small' \| 'medium' \| 'large' \| 'extraLarge' \| 'extraExtraLarge' \| (string & {})`	The size of the Avatar. `extraExtraSmall` is 24px x 24px `extraSmall` is 32px x 32px `small` is 40px x 40px `medium` is 48px x 48px `large` is 72px x 72px `extraLarge` is 96px x 96px `extraExtraLarge` is 120px x 120px	`'medium'`
`cs`		The `cs` prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using `cs`, you can merge that prop in as well. Any style that is passed to the `cs` prop will override style props. If you wish to have styles that are overridden by the `css` prop, or styles added via the `styled` API, use wherever `elemProps` is used. If your component needs to also handle style props, use instead. import {handleCsProp} from '@workday/canvas-kit-styling'; import {mergeStyles} from '@workday/canvas-kit-react/layout'; // ... // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same // function signature, but adds support for style props. return ( <Element {...handleCsProp(elemProps, [ myStyles, myModifiers({ size: 'medium' }), myVars({ backgroundColor: 'red' }) ])} > {children} </Element> )
`name`	`string`	The alt text of the Avatar image. This prop is also used for the initials. The first letter of the first name and the first letter of the second name are chosen for the initials.
`preferredInitials`	`string`	If you want full control over the initials, use `preferredInitials` instead.
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`div`
`ref`	`React.Ref<R = div>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).