# Heading

Headings strukturieren den Inhalt einer Seite in Wichtigkeitsstufen.

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

<Heading>Das ist eine Überschrift</Heading>
```

---

# Best Practices

- Beschreibe mit der Heading den folgenden Abschnitt eindeutig.
- Formuliere die Heading kurz und sachlich.
- Halte Hierarchie und Reihenfolge klar. Vermeide Sprünge, etwa von `<h2>` zu
  `<h4>`.
- Verwende pro Seite nur eine `<h1>`.

---

# Level

Über das Property `level` kann die Hierarchie der Heading angepasst werden.
Standardmäßig wird eine Heading mit dem Level `H2` erzeugt. Die Seite sollte
eine sinnvolle Struktur mit verschiedenen Ebenen aufweisen.

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

<>
  <Heading level={1}>
    Das ist eine Level 1 Überschrift
  </Heading>
  <Heading level={2}>
    Das ist eine Level 2 Überschrift
  </Heading>
  <Heading level={3}>
    Das ist eine Level 3 Überschrift
  </Heading>
  <Heading level={4}>
    Das ist eine Level 4 Überschrift
  </Heading>
  <Heading level={5}>
    Das ist eine Level 5 Überschrift
  </Heading>
</>
```

---

# Color

Zusätzlich zur Standard-Color kann die Heading in **Light** und **Dark**
dargestellt werden, wenn die Standard-Color auf farbigen oder dekorativen
Hintergründen nicht gut funktioniert. Wann welche Color passt, beschreibt
[Color](https://flow.mittwald.de/02-foundations/01-design/02-colors#light-und-dark-color).

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

<Heading color="dark">Das ist eine Überschrift</Heading>
```

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

<Heading color="light">Das ist eine Überschrift</Heading>
```

---

# Size

Über das Property `size` kann in Ausnahmefällen die Schriftgröße einer Heading
manuell angepasst werden. Die Headings sollten dabei eine visuelle Hierarchie
beibehalten.

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

<Heading level={2} size="xs">
  Das ist eine Überschrift für die eine benutzerdefinierte
  Größe gesetzt wurde
</Heading>
```

---

# Kombiniere mit ...

## ContextualHelp

Verwende eine [ContextualHelp](https://flow.mittwald.de/04-components/overlays/contextual-help), um
Usern zusätzliche Hilfestellungen zu geben (z. B. bei Fachbegriffen).

```tsx
import { Heading } from "@mittwald/flow-react-components";
import { Button } from "@mittwald/flow-react-components";
import {
  ContextualHelp,
  ContextualHelpTrigger,
} from "@mittwald/flow-react-components";
import { Text } from "@mittwald/flow-react-components";

<Heading>
  Rechte & Rollen
  <ContextualHelpTrigger>
    <Button />
    <ContextualHelp>
      <Text>
        Weitere Informationen zum Thema Rechte & Rollen
      </Text>
    </ContextualHelp>
  </ContextualHelpTrigger>
</Heading>
```

## Badge oder AlertBadge

Verwende ein [Badge](https://flow.mittwald.de/04-components/status/badge), um wichtige Metainformationen
zu einem Abschnitt hervorzuheben, oder ein
[AlertBadge](https://flow.mittwald.de/04-components/status/alert-badge), um einen Status anzuzeigen.

```tsx
import {
  AlertBadge,
  Badge,
  Heading,
} from "@mittwald/flow-react-components";

<Heading>
  E-Mail-Adresse
  <Badge>Primär</Badge>
  <AlertBadge status="danger">
    Speicherplatz voll
  </AlertBadge>
</Heading>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | `'react-aria-Heading'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static" \| "danger" \| "unavailable"` | `"default"` | The color of the heading. |
| `elementType` | `"span" \| "p" \| ExoticComponent<{}>` | - | The HTML element or React component rendered as the elements root. |
| `level` | `number` | `3` | The heading level. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `size` | `"s" \| "xs" \| "m" \| "l" \| "xl" \| "xxl"` | - | The font size of the heading. |
| `wrap` | `"wrap" \| "balance"` | `undefined` | The text-wrap property of the text. |
| `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. |

