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

## Import

```js
import { Avatar } from '@volue/wave-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>
```

> **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.

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 color="auto" />
  </Avatar.Root>
  <Avatar.Root of="Liv Margareta">
    <Avatar.Initials color="auto" />
  </Avatar.Root>
  <Avatar.Root of="Volue">
    <Avatar.Initials color="auto" />
  </Avatar.Root>
</Flex>
```

> **Tip**
>
> Set `color="auto"` on `Avatar.Initials` to assign a background colour based on the user's name. This way the identity of a user feels more unique.

### 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>
```

### Colours

`Avatar.Initials` uses `neutral` colour by default. Use the `color` property to assign a different colour, or set it to `auto` to derive the colour from the user's name.

```jsx
<Flex wrap="wrap">
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials />
  </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>
  <Avatar.Root of="Snorre Lauritz">
    <Avatar.Initials color="auto" />
  </Avatar.Root>
</Flex>
```

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

```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="neutral">
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Placeholder color="accentSubtle">
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
  <Avatar.Root of="Jorun Mathilde">
    <Avatar.Placeholder color="accent">
      <SvgIcon iconName="user" />
    </Avatar.Placeholder>
  </Avatar.Root>
</Flex>
```

### Clickable avatar with popover

You can compose the `Avatar` with a [Popover](https://next.wave-design-system.pages.dev/components/popover.md) 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 Wave'}
      </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](https://next.wave-design-system.pages.dev/components/layout/anchor.md), you can decorate `Avatar` with [Label](https://next.wave-design-system.pages.dev/components/label.md) or [HintDot](https://next.wave-design-system.pages.dev/components/hint-dot.md), 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"
      pill
      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](https://next.wave-design-system.pages.dev/get-started/composition.md#polymorphism) guide. |          |
| `css`  | `StitchesCss`                                             |            | Apply styles directly to a component in a similar way how you would define inline styles. Wave 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. Wave 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](https://next.wave-design-system.pages.dev/get-started/composition.md#polymorphism) guide. |          |
| `css`   | `StitchesCss`                                                          |             | Apply styles directly to a component in a similar way how you would define inline styles. Wave 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" \| "auto"` | `"neutral"` | The color of the initials. Set to "auto" to derive the color from 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](https://next.wave-design-system.pages.dev/get-started/composition.md#polymorphism) guide. |          |
| `css`   | `StitchesCss`                                                |                   | Apply styles directly to a component in a similar way how you would define inline styles. Wave 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"` | `"neutralSubtle"` | The colour of the placeholder.                                                                                                                                                                                                                                                                                                           |          |