# Avatar

Ein Avatar dient der visuellen Repräsentation von Usern oder anderen Inhalten, etwa durch ein Image, Initials oder ein Icon.

## Overview

# Playground

Der `<Avatar />` kann mit drei verschiedenen Components befüllt werden:
`<Image />`, `<Icon />` oder `<Initials />`.

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

---

# Color

Die Color bei der Kombination mit [Icon](/04-components/content/icon/overview)
oder Initials richtet sich jeweils nach dem übergebenen Child der Component. Für
eine gezielte Wahl der Color kann das Property `color` verwendet werden.

Folgende dekorative Colors stehen zur Verfügung: **Blue, Violet, Teal, Lilac**
und **Green**.

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

Der Avatar unterstützt die Sizes **Extra Small**, **Small**, **Medium** oder
**Large**.

```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 Color. Dieses Property darf nur verwendet werden,
wenn der Status zusätzlich durch ein benachbartes Element (z. B.
[Text](/04-components/content/text/overview) oder
[Label](/04-components/content/label/overview)) 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/overview) 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/overview).

```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/overview) kombinieren.

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

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

## Align

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

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

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


## Develop

# 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. |
| `children` | `ReactNode` | - | - |
| `className` | `string` | - | The elements class name. |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | - |
| `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` | - | - |


## Guidelines

# Grundlagen

Ein Avatar ist ein kleiner, runder Container, der ein
[Image](/04-components/content/image/overview), Initialen oder ein
[Icon](/04-components/content/icon/overview) enthalten kann. Avatare haben eine
stark visuelle, unterstützende Funktion, da sie Inhalte auf anschauliche Weise
repräsentieren. Besonders Avatare mit Images verleihen Benutzeroberflächen eine
persönlichere Note: User können ein individuelles Bild wählen (z. B. ein Profil-
oder Projektbild), wodurch die Benutzeroberfläche persönlicher und
vertrauenswürdiger wirkt. Gleichzeitig erleichtert das visuelle Feedback anderen
Usern den Aufbau einer mentalen Verbindung zu einem Profil.

## Best practices

Achte bei der Verwendung eines Avatars darauf, dass ...

- je nach Anwendungsfall die passende Variante gewählt wird. Ein Avatar mit
  [Image](/04-components/content/image/overview) eignet sich besonders für
  personalisierte Elemente wie Benutzerprofile oder Projektbilder. Ein Avatar
  mit [Icon](/04-components/content/icon/overview) passt besser zu
  wiederkehrenden Inhalten, die zum Beispiel in Lists aufgezählt werden können.
- wenn kein passendes Image im Avatar hinterlegt ist, Initialen verwendet
  werden. So bleibt die visuelle Orientierung auch ohne Bild erhalten.
- die Color-wahl sinnvoll getroffen wird. In der Regel bestimmt das enthaltene
  Element (z. B. Icon oder Initialen) die Color automatisch. In bestimmten
  Fällen kann es jedoch sinnvoll sein, eine feste Color zu definieren – z. B.
  zur besseren Unterscheidung.
- aus dem Benutzeroberflächen-Kontext klar hervorgeht, welche Bedeutung der
  Avatar hat.
- wenn mehrere Avatare nebeneinander dargestellt werden sollen, ein
  [AvatarStack](/04-components/content/avatar-stack/overview) verwendet wird, um
  die Darstellung kompakt und übersichtlich zu halten.

## Verwendung

Verwende einen Avatar, um ...

- einem übergeordneten Element eine visuelle Identität zu geben. Zum Beispiel,
  um Einträge in einer [List](/04-components/structure/list/overview) besser
  unterscheidbar zu machen.
- dem User Möglichkeiten zur Personalisierung zu bieten. Zum Beispiel um
  Benutzerprofilbilder hochzuladen oder Projekte eine visuelle Erscheinung zu
  geben.
- die visuelle Orientierung zu unterstützen. Zum Beispiel in einer
  Bestellübersicht, in der ein Avatar mit Icon anzeigt, um welche
  Zahlungsmethode es sich handelt.