# Image

Mit der Image-Component lassen sich Bilder in der Benutzeroberfläche einbinden.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
/>
```

---

# Best Practices

- Wähle Bilder, die zum Kontext und zur Gestaltung passen.
- Beschreibe Inhalt oder Zweck über einen aussagekräftigen `alt`-Text. Rein
  dekorative Bilder erhalten ein leeres `alt`-Attribut (`alt=""`).
- Optimiere die Größenverhältnisse für kurze Ladezeiten.
- Wähle Auflösung und Seitenverhältnis konsistent.
- Setze bei geringem Kontrast zum Hintergrund eine sichtbare Border.
- Verzichte möglichst auf Text im Bild. Screenreader erfassen ihn nicht.
- Nutze für verschiedene Bildschirmgrößen das `srcSet`-Attribut. Es wählt je
  nach Pixeldichte automatisch die passende Auflösung (siehe
  [Responsive Images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_same_size_different_resolutions:~:text=Resolution%20switching%3A%20Same%20size%2C%20different%20resolutions)).

---

# Border

Mit der Property `withBorder` erhält die Image-Component eine Border und
zusätzlich einen Border Radius. Das ist insbesondere bei Bildern mit geringem
Kontrast zum Hintergrund von Vorteil, da es die visuelle Abgrenzung verbessert
und die Bildwahrnehmung unterstützt.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
  withBorder
/>
```

---

# Fixes Seitenverhältnis

Die Property `aspectRatio` definiert das Seitenverhältnis der Image-Component.
Weicht das Seitenverhältnis des eingebetteten Bildes ab – etwa durch eine
größere Höhe oder Breite –, wird das Bild zentriert, und überstehende Bereiche
außerhalb des festgelegten Verhältnisses werden ausgeblendet.

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

<Image
  src="https://flow.mittwald.de/assets/mittwald_logo_rgb.jpg"
  alt="mittwald"
  width={200}
  aspectRatio={16 / 9}
  withBorder
/>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aspectRatio` | `number` | - | The aspect ratio of the images container. Larger images will be centered and their overflow will be hidden. |
| `withBorder` | `boolean` | - | Display the image with border and rounded edges. |
| `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. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. @see aria-labelledby |
| `aria-hidden` | `Booleanish` | - | Indicates whether the element is exposed to an accessibility API. @see aria-disabled. |
| `aria-label` | `string` | - | Defines a string value that labels the current element. @see aria-labelledby. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. @see aria-describedby. |