# Avatar
> Avatar is a visual representation of a user in the interface.

## Import

```js
import { Avatar } from '@gemini-suite/vera-react';
```

Avatar is a compound component that consists of multiple parts:

- `Avatar.Root`: The wrapper that contains all the parts of an avatar and provides context for its children.
- `Avatar.Image`: The image that represents the user.
- `Avatar.Fallback`: A container for a fallback content that should render when the image hasn't loaded or is unavailable.
- `Avatar.Initials`: The initials of the user's name to render.
- `Avatar.Placeholder`: The placeholder like an icon to render.

## Examples

### With image

Provide thumbnail image of a user whenever available. The image will only render when it has loaded. Whilst it's loading, the provided fallback will display.

```jsx
<Flex>
  <Avatar.Root of="Torvald Halvor">
    <Avatar.Image src="https://images.unsplash.com/photo-1552058544-f2b08422138a?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
    <Avatar.Fallback>
      <Avatar.Initials />
    </Avatar.Fallback>
  </Avatar.Root>
  <Avatar.Root of="Mikael Rikard">
    <Avatar.Image src="https://images.unsplash.com/photo-1528892952291-009c663ce843?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
    <Avatar.Fallback>
      <Avatar.Initials />
    </Avatar.Fallback>
  </Avatar.Root>
  <Avatar.Root of="Ragnhild Tine">
    <Avatar.Image src="https://images.unsplash.com/photo-1498529605908-f357a9af7bf5?ixlib=rb-0.3.5&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;s=047fade70e80ebb22ac8f09c04872c40" />
    <Avatar.Fallback>
      <Avatar.Initials />
    </Avatar.Fallback>
  </Avatar.Root>
</Flex>
```

<Callout variant="tip">

You can optionally delay fallback rendering, by specifying `delayMs` prop.
This may be useful to prevent content flashing and render placeholder only for those with slower connections.

</Callout>

If the image is unavailable or if there was an error while loading it, only the fallback will display. You can choose to provide user name initials as a fallback or a dull human silhouette placeholder.

```jsx
<Flex>
  <Avatar.Root of="Liv Margareta">
    <Avatar.Image src="https://api.lorem.space" />
    <Avatar.Fallback>
      <Avatar.Initials />
    </Avatar.Fallback>
  </Avatar.Root>
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Image src="https://api.lorem.space" />
    <Avatar.Fallback>
      <Avatar.Placeholder>
        <SvgIcon iconName="user" />
      </Avatar.Placeholder>
    </Avatar.Fallback>
  </Avatar.Root>
</Flex>
```

### Just initials

If you can't provide a user image, displaying initials is the best alternative. Note that no fallback is needed in that case.

```jsx
<Flex wrap="wrap">
  <Avatar.Root of="Ulf Sindre">
    <Avatar.Initials />
  </Avatar.Root>
  <Avatar.Root of="Inge Arnt">
    <Avatar.Initials />
  </Avatar.Root>
  <Avatar.Root of="Liv Margareta">
    <Avatar.Initials />
  </Avatar.Root>
  <Avatar.Root of="Volue">
    <Avatar.Initials />
  </Avatar.Root>
</Flex>
```

<Callout variant="tip">

Background and color of the initials is based on the user's name. This way the identity of a user feels more unique.

</Callout>

### Size

The `Avatar` component comes in `medium` and `small` sizes to accommodate different use cases. To adjust the size, pass `size` prop.

```jsx
<Flex wrap="wrap">
  <Avatar.Root of="Fritjof Snorre" size="small">
    <Avatar.Initials />
  </Avatar.Root>
  <Avatar.Root of="Fritjof Snorre" size="small">
    <Avatar.Image src="https://images.unsplash.com/photo-1548946526-f69e2424cf45?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
    <Avatar.Fallback>
      <Avatar.Initials />
    </Avatar.Fallback>
  </Avatar.Root>
  <Avatar.Root of="Liv Margareta" size="medium">
    <Avatar.Initials />
  </Avatar.Root>
  <Avatar.Root of="Liv Margareta" size="medium">
    <Avatar.Image src="https://images.unsplash.com/photo-1493666438817-866a91353ca9?ixlib=rb-0.3.5&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;s=b616b2c5b373a80ffc9636ba24f7a4a9" />
    <Avatar.Fallback>
      <Avatar.Initials />
    </Avatar.Fallback>
  </Avatar.Root>
</Flex>
```

### Colors

`Avatar.Initials` picks color based on the user's name by default, but you can assign fixed color value with a `color` property.

```jsx
<Flex wrap="wrap">
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials />
  </Avatar.Root>
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials color="neutral" />
  </Avatar.Root>
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials color="neutralSubtle" />
  </Avatar.Root>
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials color="accent" />
  </Avatar.Root>
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials color="accentSubtle" />
  </Avatar.Root>
</Flex>
```

Likewise, you can use `color` property to change `Avatar.Fallback` default color.

```jsx
<Flex wrap="wrap">
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Placeholder>
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Placeholder color="neutralSubtle">
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Placeholder color="accent">
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Placeholder color="accentSubtle">
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
</Flex>
```

### Clickable Avatar with popover

You can compose the `Avatar` with a [Popover](/components/popover) to display extra information.

```jsx
<Popover.Root>
  <Popover.Trigger>
    <Avatar.Root of="Fritjof Snorre">
      <Avatar.Image src="https://images.unsplash.com/photo-1548946526-f69e2424cf45?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
      <Avatar.Fallback>
        <Avatar.Initials />
      </Avatar.Fallback>
    </Avatar.Root>
  </Popover.Trigger>
  <Popover.Content padding="spacingM">
    <Flex flow="column" gap="none">
      <Text>{'Fritjof Snorre'}</Text>
      <Text variant="zeta" color="foregroundNeutralModerate">
        {'Logged in to Vera'}
      </Text>
      <Box marginTop="spacingM">
        <Popover.Close as={Button}>{'Log out'}</Popover.Close>
      </Box>
    </Flex>
  </Popover.Content>
</Popover.Root>
```

### With indicators

With help of [Anchor component](/components/layout/anchor), you can decorate `Avatar` with [Label](/components/label) or [HintDot](/components/hint-dot), to show presence indicators, notification count and alike.

```jsx
<Flex>
  <Anchor.Root>
    <Avatar.Root of="Fritjof Snorre">
      <Avatar.Image src="https://images.unsplash.com/photo-1548946526-f69e2424cf45?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
      <Avatar.Fallback>
        <Avatar.Initials />
      </Avatar.Fallback>
    </Avatar.Root>
    <Anchor.Target
      position="bottom-end"
      inset="14%"
      as={HintDot}
      showOutlineRing
      tone="success"
      role="status"
      aria-label="Active"
    />
  </Anchor.Root>
  <Anchor.Root>
    <Avatar.Root of="Liv Margareta">
      <Avatar.Image src="https://images.unsplash.com/photo-1493666438817-866a91353ca9?ixlib=rb-0.3.5&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;s=b616b2c5b373a80ffc9636ba24f7a4a9" />
      <Avatar.Fallback>
        <Avatar.Initials />
      </Avatar.Fallback>
    </Avatar.Root>
    <Anchor.Target
      position="bottom-end"
      inset="14%"
      as={HintDot}
      showOutlineRing
      tone="danger"
      role="status"
      aria-label="Busy"
    />
  </Anchor.Root>
  <Anchor.Root>
    <Avatar.Root of="Torvald Halvor">
      <Avatar.Image src="https://images.unsplash.com/photo-1552058544-f2b08422138a?ixlib=rb-1.2.1&amp;q=80&amp;fm=jpg&amp;crop=faces&amp;fit=crop&amp;h=200&amp;w=200&amp;ixid=eyJhcHBfaWQiOjE3Nzg0fQ" />
      <Avatar.Fallback>
        <Avatar.Initials />
      </Avatar.Fallback>
    </Avatar.Root>
    <Anchor.Target
      inset="14%"
      as={Label}
      color="danger"
      circular
      size="small"
      showOutlineRing
    >
      5
    </Anchor.Target>
  </Anchor.Root>
</Flex>
```

---

## API Reference

### Avatar.Root

| Name   | Type                                                      | Default    | Description                                                                                                                                                                                                                                                                                  | Required |
| ------ | --------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`   | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`      | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`  | `StitchesCss`                                             |            | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `of`   | `string`                                                  |            | Full name of the person in the avatar. It will be used as the `alt` attribute of the `img` and to create the initials.                                                                                                                                                                       | Yes      |
| `size` | `"small" \| "medium"`                                     | `"medium"` | The size of the avatar.                                                                                                                                                                                                                                                                      |          |

### Avatar.Image

| Name                    | Type                                                           | Default | Description                                                                                                                                                                                                                                  | Required |
| ----------------------- | -------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`                   | `StitchesCss`                                                  |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `src`                   | `string`                                                       | `false` | The url of the image.                                                                                                                                                                                                                        |          |
| `onLoadingStatusChange` | `(status: "idle" \| "loading" \| "loaded" \| "error") => void` |         | A callback providing information about the loading status of the image. This is useful in case you want to control more precisely what to render as the image is loading.                                                                    |          |

### Avatar.Fallback

| Name       | Type              | Default | Description                                                                                                                              | Required |
| ---------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `children` | `React.ReactNode` |         | The children to render as fallback when the image hasn't loaded. Ideally should be `Avatar.Initials` or `Avatar.Placeholder` components. | Yes      |

### Avatar.Initials

| Name    | Type                                                                   | Default  | Description                                                                                                                                                                                                                                                                                  | Required |
| ------- | ---------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`    | `keyof JSX.IntrinsicElements \| React.ComponentType<any>`              | `div`    | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`   | `StitchesCss`                                                          |          | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |
| `color` | `"auto" \| "neutral" \| "neutralSubtle" \| "accent" \| "accentSubtle"` | `"auto"` | The color of the initials. By default the color is based on the user's name.                                                                                                                                                                                                                 |          |

### Avatar.Placeholder

| Name    | Type                                                         | Default     | Description                                                                                                                                                                                                                                                                                  | Required |
| ------- | ------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`    | `keyof JSX.IntrinsicElements \| React.ComponentType<any>`    | `div`       | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`   | `StitchesCss`                                                |             | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |
| `color` | `"neutral" \| "neutralSubtle" \| "accent" \| "accentSubtle"` | `"neutral"` | The color of the placeholder.                                                                                                                                                                                                                                                                |          |