# Avatar

An Avatar is used to display a visual identifier for an individual user.

## Design & usage guidelines

Avatars are available in 3 sizes:

* `base`: Used by default
* `large`: Use when the Avatar is the focal point
* `small`: Use on higher-density/compact pages or components

### Color

Use `color` to indicate the background and the border color of an Avatar
component.

When using `color`, make sure that the color is consistent for a user throughout
the application. The color that is represented for an Avatar should be the same
color that represents a user in other parts of the application, such as the
calendar.

### With Tooltip

If an Avatar is displayed without a full name label, display a tooltip.

## Accessibility

Initials and background color should have sufficient color contrast to meet AA
conformance.


## Component customization

### UNSAFE\_ props (advanced usage)

General information for using `UNSAFE_` props can be found
[here](../customizing-components/customizing-components.md).

**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
considered a **last resort**. Future Icon updates may lead to unintended
breakages.

#### UNSAFE\_props (web)

### UNSAFE\_className

Use `UNSAFE_className` to apply custom classes to the Avatar component. This can be
useful for applying styles via CSS Modules.

```tsx
// For Avatar with image
<Avatar
  name="Custom Container Class Name"
  imageUrl="https://api.adorable.io/avatars/150/jobbler"
  UNSAFE_className={{ container: styles.customContainerClassName }}
/>

// For Avatar with initials
<Avatar
  initials="JB"
  UNSAFE_className={{ initials: styles.customInitialsClassName }}
/>,

// For Avatar with fallback icon
<Avatar
  initials=""
  UNSAFE_className={{
    fallbackIcon: {
      svg: styles.customFallbackIconSvgClassName,
      path: styles.customFallbackIconPathClassName,
    },
  }}
/>

// YourComponent.module.css
.customContainerClassName {
  border-color: var(--color-red);
}

.customInitialsClassName {
  color: var(--color-blue);
}

.customFallbackIconSvgClassName {
  width: 59px;
  height: 59px;
}

.customFallbackIconPathClassName {
  fill: var(--color-blue);
}
```

### UNSAFE\_style

Use `UNSAFE_style` to apply inline custom styles to the Avatar component.

```tsx
// For Avatar with image
 <Avatar
  name="Custom Container Style"
  imageUrl="https://api.adorable.io/avatars/150/jobbler"
  UNSAFE_style={{
    container: {
      borderColor: "var(--color-green)",
    },
  }}
/>

// For Avatar with initials
<Avatar
  initials="JB"
  UNSAFE_style={{ initials: { color: "var(--color-blue)" } }}
/>

// For Avatar with fallback icon
<Avatar
  initials=""
  UNSAFE_style={{
    fallbackIcon: {
      svg: {
        width: "59px",
        height: "59px",
      },
      path: {
        fill: "var(--color-blue)",
      },
    },
  }}
/>,
```


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `color` | `string` | No | — | The background and border color that represents the user. This should be represented as a value that can be read by CSS |
| `imageUrl` | `string` | No | — | A url for the image that will be displayed |
| `initials` | `string` | No | — | The initials that will be displayed if no image is set.\ |
| `name` | `string` | No | — | A users name to be used for assistive technology |
| `size` | `AvatarSize` | No | `base` | Change the size of the avatar @property "large" - Make avatar to be the focal point @property "small" - For higher-de... |
| `UNSAFE_className` | `{ container?: string; } & InitialsUnsafeClassNameProps` | No | `{}` | **Use at your own risk:** Custom class names for specific elements. This should only be used as a **last resort**. Us... |
| `UNSAFE_style` | `{ container?: CSSProperties; } & InitialsUnsafeStyleProps` | No | `{}` | **Use at your own risk:** Custom style for specific elements. This should only be used as a **last resort**. Using th... |