# Avatar

Ein Avatar repräsentiert User visuell, per Image, Initials oder Icon.

```tsx
import {
  Avatar,
  Image,
} from "@mittwald/flow-react-components";

<Avatar>
  <Image
    alt="Gopher"
    src="https://cdn.shopify.com/s/files/1/2022/6883/products/IMG_2002_250x250@2x.JPG?v=1538235544"
  />
</Avatar>
```

---

# Best Practices

- Wähle die passende Variante je nach Anwendungsfall. Ein
  [Image](/04-components/content/image) eignet sich für personalisierte Elemente
  wie Benutzerprofile, ein [Icon](/04-components/content/icon) für
  wiederkehrende Inhalte.
- Zeige Initialen, wenn kein passendes Image hinterlegt ist.
- Überlass die Farbe meist dem enthaltenen Element. Setze über `color` nur dann
  eine feste Farbe, wenn sie die Unterscheidung verbessert.
- Sorge dafür, dass die Bedeutung des Avatars aus dem Kontext hervorgeht.
- Nutze bei mehreren Avataren nebeneinander einen
  [AvatarStack](/04-components/content/avatar-stack).

---

# Color

Initials erhalten automatisch eine der Colors, abhängig von ihrem Inhalt. Ein
[Icon](/04-components/content/icon) erhält über den Avatar im Default die Color
`blue`. Für eine gezielte Wahl kann das Property `color` verwendet werden.

```tsx
import {
  Avatar,
  IconCustomer,
  IconHome,
  Initials,
} from "@mittwald/flow-react-components";

<>
  <Avatar>
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar>
    <Initials>Gina-Lisa Gopher</Initials>
  </Avatar>
  <Avatar color="lilac">
    <Initials>Gilian Gopher</Initials>
  </Avatar>
  <Avatar>
    <IconHome />
  </Avatar>
  <Avatar>
    <IconCustomer />
  </Avatar>
</>
```

---

# Sizes

```tsx
import {
  Avatar,
  Initials,
} from "@mittwald/flow-react-components";

<>
  <Avatar size="xs">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar size="s">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar size="m">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
  <Avatar size="l">
    <Initials>Gillian Gopher</Initials>
  </Avatar>
</>
```

---

# Status

Wird im Avatar das Property `status` gesetzt erhält der Avatar automatisch das
passende Icon und die passende Farbe. Dieses Property darf nur verwendet werden,
wenn der Status zusätzlich durch ein benachbartes Element (z. B.
[Text](/04-components/content/text) oder [Label](/04-components/content/label))
eindeutig kommuniziert wird.

```tsx
import { Avatar } from "@mittwald/flow-react-components";

<>
  <Avatar status="info" />
  <Avatar status="success" />
  <Avatar status="warning" />
  <Avatar status="danger" />
  <Avatar status="unavailable" />
</>
```

```tsx
import {
  AlertBadge,
  Avatar,
  Heading,
  IconEmail,
  Section,
  Text,
  typedList,
} from "@mittwald/flow-react-components";

export default () => {
  const NotificationList = typedList<{
    status: "info" | "success" | "danger" | "warning";
    content: string;
  }>();

  const EmailList = typedList<{
    address: string;
    blocked?: boolean;
  }>();

  return (
    <>
      <Section>
        <Heading>Benachrichtigungen</Heading>
        <Text>
          Hier wird der Status durch den Inhalt der
          Benachrichtigung erklärt, daher kann der Status
          Avatar verwendet werden.
        </Text>

        <NotificationList.List>
          <NotificationList.StaticData
            data={[
              {
                status: "danger",
                content:
                  'E-Mail-Adresse "mail@example.de" gesperrt',
              },
              {
                status: "success",
                content: "App erfolgreich angelegt",
              },
            ]}
          />
          <NotificationList.Item
            textValue={(notification) =>
              notification.content
            }
          >
            {(notification) => (
              <NotificationList.ItemView>
                <Avatar status={notification.status} />
                <Heading>{notification.content}</Heading>
              </NotificationList.ItemView>
            )}
          </NotificationList.Item>
        </NotificationList.List>
      </Section>
      <Section>
        <Heading>E-Mail-Adressen</Heading>
        <Text>
          Hier muss der Status durch das AlertBadge erklärt
          werden, der Status Avatar kann daher nicht
          verwendet werden.
        </Text>
        <EmailList.List>
          <EmailList.StaticData
            data={[
              {
                address: "mail@example.de",
                blocked: true,
              },
              {
                address: "info@example.de",
              },
            ]}
          />
          <EmailList.Item
            textValue={(email) => email.address}
          >
            {(email) => (
              <EmailList.ItemView>
                <Avatar>
                  <IconEmail />
                </Avatar>
                <Heading>
                  {email.address}
                  {email.blocked && (
                    <AlertBadge status="danger">
                      E-Mail-Adresse gesperrt
                    </AlertBadge>
                  )}
                </Heading>
              </EmailList.ItemView>
            )}
          </EmailList.Item>
        </EmailList.List>
      </Section>
    </>
  );
}
```

---

# Kombiniere mit ...

## Image

Im folgenden Code-Beispiel wird ein Avatar mit einem
[Image](/04-components/content/image) kombiniert. Wenn kein Image vorhanden ist,
sollten Initials angezeigt werden.

```tsx
import {
  Avatar,
  Image,
} from "@mittwald/flow-react-components";

<Avatar>
  <Image
    alt="Gopher"
    src="https://cdn.shopify.com/s/files/1/2022/6883/products/IMG_2002_250x250@2x.JPG?v=1538235544"
  />
</Avatar>
```

Die Initials werden automatisch aus dem Text generiert, der innerhalb von
`<Initials />` übergeben wird. Sie dienen ausschließlich als Platzhalter für ein
[Image](/04-components/content/image).

```tsx
import {
  Avatar,
  Initials,
} from "@mittwald/flow-react-components";

<Avatar>
  <Initials>Gillian Gopher</Initials>
</Avatar>
```

## Icon

Ein Avatar lässt sich mit einem beliebigen [Icon](/04-components/content/icon)
kombinieren.

```tsx
import {
  Avatar,
  IconHome,
} from "@mittwald/flow-react-components";

<Avatar color="blue">
  <IconHome />
</Avatar>
```

## Combine

Benutze die [Combine](/04-components/structure/combine)-Component, um Text neben
dem Avatar zu platzieren.

```tsx
import {
  Combine,
  Avatar,
  Initials,
  Text,
} from "@mittwald/flow-react-components";

<Combine>
  <Avatar>
    <Initials>Max Mustermann</Initials>
  </Avatar>
  <Text>
    <strong>Max Mustermann</strong>
    Organisationsinhaber
  </Text>
</Combine>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"s" \| "xs" \| "m" \| "l"` | `"m"` | The size of the avatar. |
| `color` | `"violet" \| "green" \| "blue" \| "teal" \| "lilac"` | - | The color of icons and initials inside the avatar. |
| `status` | `"info" \| "success" \| "warning" \| "danger" \| "unavailable"` | - | Adds status icon and color to the avatar. May only be used if the status is explained by an element (like text or label) nearby. |
| `label` | `string` | - | A descriptive label that assistive technology announces for the avatar (e.g. the name of the represented person or entity). When set, the avatar is exposed as a single image with this label. When omitted, the avatar is treated as purely decorative and hidden from assistive technology. |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup. |
| `ref` | `Ref<HTMLSpanElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see [React Docs](https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom) |
| `key` | `Key` | - | - |