# Avatar

This component is intended for rendering avatars. It has three basic avatar types: image, icon, and text (name initials). All these types have special properties to configure the behavior and appearance.

```tsx
import {Avatar} from '@gravity-ui/uikit';
```

## Types

### Image

This component can be used to render avatars using images. To provide an image, use the `imgUrl` property.

You can also provide the `srcSet` property to load images of different sizes.

The `Avatar` component has the `fallbackImgUrl` property which allows you to provide the image that is shown when an image loading error occurs, through the `imgUrl` link (CSP error or no original image).

### Icon

This component can be used to render avatars using icons. Use the `icon` property to provide an icon, just like you would do in case of the `Icon` component.

### Text

This component can be used to render avatars using text. Use the `text` property for that. The text is rendered as initials (first letters of two words) or just two first letters of a single word.

## Appearance

### Theme and view

The `Avatar` component has predefined themes (`normal`, `brand`) and views (`filled`, `outlined`).

The default theme is `normal` and the default view is `filled`.

### Custom colors

You can also provide custom colors through the `backgroundColor`, `borderColor`, and `color` properties (the latter works only for icon and text avatars). These colors have a higher priority than the theme colors.

### Size

Use the `size` property to manage the `Avatar` size. The default size is `m`. The possible values are `3xs`, `2xs`, `xs`, `s`, `m`, `l`, and `xl`.

### Shape

Use the `shape` property to manage the `Avatar` shape. The default shape is `circle`. The possible values are `circle` and `square`.

## Properties

### Common

| Name             | Description                                |                      Type                       | Default  |
| :--------------- | :----------------------------------------- | :---------------------------------------------: | :------: |
| size             | Avatar size                                | `'3xs'` `'2xs'` `'xs'` `'s'` `'m'` `'l'` `'xl'` |   `m`    |
| theme            | Avatar theme                               |              `'normal'` `'brand'`               | `normal` |
| view             | Avatar filling and outlining options       |             `'filled'` `'outlined'`             | `filled` |
| shape            | Avatar shape                               |              `'circle'` `'square'`              | `circle` |
| backgroundColor  | Custom background color                    |                    `string`                     |          |
| borderColor      | Custom border color                        |                    `string`                     |          |
| title            | `title` HTML attribute                     |                    `string`                     |          |
| aria-label       | `aria-label` for the avatar section        |                    `string`                     |          |
| aria-labelledby  | `aria-labelledby` for the avatar section   |                    `string`                     |          |
| aria-describedby | `aria-describedby` for avatar block        |                    `string`                     |          |
| aria-details     | `aria-details` for avatar block            |                    `string`                     |          |
| className        | Custom CSS class for the root element      |                    `string`                     |          |
| style            | `style` HTML attribute                     |              `React.CSSProperties`              |          |
| qa               | `data-qa` HTML attribute, used for testing |                    `string`                     |          |

### Image-specific

| Name            | Description                               |        Type        |   Default   |
| :-------------- | :---------------------------------------- | :----------------: | :---------: |
| imgUrl          | `img` `src` HTML attribute                |      `string`      |             |
| fallbackImgUrl  | Fallback image shown if an error occurred |      `string`      |             |
| sizes           | `img` `sizes` HTML attribute              |      `string`      |             |
| srcSet          | `img` `srcSet` HTML attribute             |      `string`      |             |
| alt             | `img` `alt` HTML attribute                |      `string`      | props.title |
| loading         | `img` `loading` HTML attribute            | `'eager'` `'lazy'` |             |
| withImageBorder | Add default border for the image          |     `boolean`      |             |

### Icon-specific

| Name  | Description        |    Type    | Default |
| :---- | :----------------- | :--------: | :-----: |
| icon  | Source of SVG icon | `IconData` |         |
| color | Custom icon color  |  `string`  |         |

### Text-specific

| Name  | Description       |   Type   | Default |
| :---- | :---------------- | :------: | :-----: |
| text  | Avatar text       | `string` |         |
| color | Custom text color | `string` |         |

## CSS API

| Name                            | Description             |
| :------------------------------ | :---------------------- |
| `--g-avatar-size`               | Size (width and height) |
| `--g-avatar-border-width`       | Border width            |
| `--g-avatar-inner-border-width` | Inner border width      |
| `--g-avatar-border-color`       | Border color            |
| `--g-avatar-background-color`   | Background color        |
| `--g-avatar-text-color`         | Icon and text color     |
| `--g-avatar-font-weight`        | Text font weight        |
| `--g-avatar-font-size`          | Text font size          |
| `--g-avatar-line-height`        | Text line height        |