Avatar

Anatomy

1. Background: A randomly selected fill color for the initial-based variant.
2. Initials: The first letters of a user’s first and last names in a darker gradient of fill color.
3. 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-preview-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

HD

⚡️ Edit in StackblitzShow Code

import {Avatar} from '@workday/canvas-kit-preview-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-preview-react/avatar';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

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

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-preview-react/avatar';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

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

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" />
    </div>
  );
};

Advanced Custom Component

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

import {BaseAvatar} from '@workday/canvas-kit-preview-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.

NS

Nicholas Smith

⚡️ Edit in StackblitzShow Code

import {Avatar} from '@workday/canvas-kit-preview-react/avatar';
// @ts-ignore
import nicholasAvatar from './nicholas-avatar.jpg';
import {createStyles} from '@workday/canvas-kit-styling';
import {Text} from '@workday/canvas-kit-react/text';
import {system} from '@workday/canvas-tokens-web';
const containerStyles = createStyles({
  display: 'inline-flex',
  gap: system.space.x2,
  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

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>
)

Anatomy

1. Background: A randomly selected fill color for the initial-based variant.
2. Initials: The first letters of a user’s first and last names in a darker gradient of fill color.
3. Stroke: The outer circle for the initial-based variant.
4. 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.

Behaviors

Pressed States

Pressed states pertain to Avatars in standalone instances only. Avatars that are part of a larger selection item do not have individual pressed behaviors.

Disabled States

Disabled states apply only for non-standalone Avatars, which are a sub-component in a larger composite component such as an Avatar in a list item.

Loading States

The Avatar should not default to a generic user icon when loading. The Avatar has a skeleton that accommodates different background colors when loading.

Examples

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.

Background

Against darker gradients, white strokes are used to increase contrast. The initial-based variant stroke becomes white and a white stroke is added around the image-based variant.

Color

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

API Guidelines

Methods

Class name: Avatar Module name: UIComponentsPlugin

    public init(
        featureData: FeatureMetricsData,
        context: SemanticContext = .default,
        imageType: ImageType,
        avatarSize: AvatarSize,
        avatarColor: AvatarColor = .chiliMango,
        isOnDarkBackground: Bool = false,
        isEnabled: Bool = true,
        isLoading: Bool = false,
        onClick: @escaping (() -> Void) = {}
    )

Parameters

Accessibility Guidelines

Coming soon…

Anatomy

1. Background: A randomly selected fill color for the initial-based variant.
2. Initials: The first letters of a user’s first and last names in a darker gradient of fill color.
3. Stroke: The outer circle for the initial-based variant.
4. 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.

Behaviors

Pressed States

Pressed states pertain to Avatars in standalone instances only. Avatars that are part of a larger selection item do not have individual pressed behaviors.

Disabled States

Disabled states apply only for non-standalone Avatars, which are a sub-component in a larger composite component such as an Avatar in a list item.

Loading States

The Avatar should not default to a generic user icon when loading. The Avatar has a skeleton that accommodates different background colors when loading.

Examples

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.

Background

Against darker gradients, white strokes are used to increase contrast. The initial-based variant stroke becomes white and a white stroke is added around the image-based variant.

Color

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

API Guidelines

Methods

  fun AvatarUiComponent(
    modifier: Modifier = Modifier,
    avatarSizeConfig: AvatarSizeConfig = AvatarSizeConfig.S,
    avatarColorConfig: AvatarColorConfig = AvatarColorConfig.ChiliMango,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    onColorBackground: Boolean = false,
    enabled: Boolean = true,
    isLoading: Boolean = false,
    initials: String,
    imageResourceId: Int? = null,
    bitmap: Bitmap? = null,
    role: Role? = null,
    onClick: (() -> Unit)? = null,
)

Parameters

Accessibility Guidelines

Coming soon…