@gravity-ui/uikit
Version:
Gravity UI base styling and components
107 lines (74 loc) • 5.92 kB
Markdown
# 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 |