# Badge

Ein Badge stellt kompakt zusätzliche Informationen wie Metadaten, Status oder Kategorien dar. Es unterstützt die schnelle Orientierung, ohne vom Hauptinhalt abzulenken.

## Overview

# Playground

Verwende `<Badge />`, um ein Badge darzustellen.

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

<Badge>Value</Badge>
```

---

# Mit Scope

Ein Scope ist wie eine Bezeichnung für das gesamte Badge. Ein Scope besitzt
meistens mehrere Werte z. B. Priorität: hoch, Priorität: niedrig.

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

<Badge color="neutral">
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

---

# Badge Aktion

Ein Badge kann optional mit `onPress` eine Aktion auslösen, sollte jedoch nicht
so vielseitig wie ein Button verwendet werden.

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

<Badge
  onPress={() => {
    alert("pressed!");
  }}
>
  Value
</Badge>
```

---

# Badge entfernen

Ein Badge kann optional vom User aus der Benutzeroberfläche entfernt werden.

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

<Badge
  onClose={() => {
    alert("closed!");
  }}
>
  Value
</Badge>
```

---

# Color

Es stehen insgesamt 9 Badge-Colors zur Auswahl: **Neutral**, **Blue**, **Navy**,
**Violet**, **Teal**, **Lilac**, **Green**, **Orange** und **Red**.

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

<>
  <Badge color="neutral">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="blue">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="navy">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="violet">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="teal">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="lilac">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="green">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="orange">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
  <Badge color="red">
    <Label>Scope</Label>
    <Text>Value</Text>
  </Badge>
</>
```

Die verschiedenen [Color](/02-foundations/01-design/02-colors)-Varianten können
frei verwendet werden. Dabei sollte jedoch immer die beabsichtigte visuelle
Wirkung berücksichtigt werden. **Neutral** eignet sich beispielsweise für
begleitende oder sekundäre Informationen, da das dezente Grau weniger
Aufmerksamkeit erzeugt. **Violet** kann dagegen gut eingesetzt werden, um neue
Inhalte oder Features hervorzuheben.

Setze die Colors **Blue, Green, Orange** und **Red** mit Bedacht ein, da sie
leicht mit [AlertBadges](/04-components/status/alert-badge/overview) oder
Status-Colors verwechselt werden.

## Light und Dark

Zusätzlich kann das Badge in Light und Dark dargestellt werden. Beide Varianten
eigenen sich, wenn die Standardfarben auf farbigen oder dekorativen
Hintergründen nicht gut funktionieren.

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

<Badge color="light">
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

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

<Badge color="dark">
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```

---

# Disabled

In Ausnahmefällen können deaktivierte Badges verwendet werden, um eine Funktion
temporär als nicht verfügbar darzustellen, ohne diese vollständig aus der
Oberfläche zu entfernen.

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

<Badge color="neutral" isDisabled>
  <Label>Scope</Label>
  <Text>Value</Text>
</Badge>
```


## Develop

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"dark" \| "light" \| "dark-static" \| "light-static" \| "neutral" \| "violet" \| "green" \| "blue" \| "teal" \| "lilac" \| "navy" \| "orange" \| "red"` | `"neutral"` | The color of the badge. |
| `isDisabled` | `boolean` | - | Whether the badge is disabled. |
| `children` | `ReactNode` | - | - |
| `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` | - | - |
| `className` | `string` | - | The elements class name. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onPress` | `((e: PressEvent) => void)` | - | Handler that is called when the badge is pressed. |
| `onClose` | `((e: PressEvent) => void)` | - | Handler that is called when the badges close icon is pressed. |


## Guidelines

# Grundlagen

## Best practices

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

- die Beschreibung kurz und prägnant ist (idealerweise in 1–3 Wörtern).
- die Farben konsistent für bestimmte Informationen verwendet werden.
- mithilfe eines Scopes dem Badge eine übergeordnete Bezeichnung hinzugefügt
  wird.
- diese für Metadaten und Kategorien verwendet wird. Bei kritischere
  Informationen wird eher eine
  [AlertBadge](/04-components/status/alert-badge/overview) in Kombination eines
  [Alert](/04-components/status/alert/overview) verwendet.

## Verwendung

Verwende einen Badge, um ...

- Metadaten hervorzuheben (z. B. Bezahlt, Überfällig, Entwurf).
- einen Status zu kennzeichnen (z. B. Aktiviert, Deaktiviert).
- eine Kategorie oder Zugehörigkeit darzustellen (z. B. Support, Marketing,
  Entwicklung).
- wichtige Änderungen und Neuerungen hervorzuheben (z. B. Neu, Beta, Update).
- Prioritäten zu kennzeichnen (z. B. Priorität: Hoch, Priorität: Mittel,
  Priorität: Niedrig).
- gesetzte Filter in der [List](/04-components/structure/list/overview)
  darzustellen.

## Badge vs. AlertBadge

  

- Metadaten oder ergänzende Informationen dargestellt werden sollen.
    - keine sofortige Aktion oder erhöhte Aufmerksamkeit notwendig ist.

   

- der Hinweis kritisch, sicherheitsrelevant oder besonders wichtig ist.
    - weitere Informationen durch einen [Alert](/04-components/status/alert/overview) notwendig sind.