# TextField

Ein TextField ermöglicht es dem Nutzer, Text über die Tastatur in ein User Interface einzugeben. Ein Label und eine optionale FieldDescription unterstützen dabei, die Anforderungen an die Eingabe klar zu kommunizieren.

## Guidelines

# Grundlagen

## Best practices

- Frage nur nach Informationen, die wirklich notwendig sind.
- Stelle sicher, dass das [Label](/04-components/content/label/overview)
  prägnant, vollständig sichtbar und leicht verständlich ist.
- Verwende die FieldDescription für sinnvolle Beispiele oder
  Formatierungshinweise.
- Stelle sicher, dass Fehlermeldungen hilfreich sind, eine Lösung bieten und
  leicht umzusetzen sind.
- Verwende keine Placeholder für wesentliche Informationen.

---

# Anwendung

## Position

Das TextField wird meistens innerhalb eines
[ColumnLayouts](/04-components/structure/column-layout/overview) platziert und
füllt dort immer die zur Verfügung stehende Breite. Dadurch folgt es auch einer
Aufteilung in Spalten, sofern das ColumnLayout eine vorsieht. Am besten eignet
sich ein 1:1 Raster für TextFields, sodass sie maximal die Hälfte des
Content-Bereichs einnehmen können. Das ColumnLayout kann zudem erweitert werden,
um spezifischeren Layoutanforderungen gerecht zu werden.

**✅ Do**

Nutze ein 1:1 [ColumnLayout](/04-components/structure/column-layout/overview) für
TextFields. Darin kann ein weiteres Raster (z. B. 2:1) verwendet werden, um
sinnvolle Gruppierungen (z. B. Straße und Hausnummer) innerhalb des Layouts zu
erstellen.

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

<ColumnLayout m={[1, 1]}>
  <TextField isRequired>
    <Label>Vorname</Label>
  </TextField>
  <TextField isRequired>
    <Label>Nachname</Label>
  </TextField>
  <ColumnLayout s={[2, 1]}>
    <TextField isRequired>
      <Label>Straße</Label>
    </TextField>
    <TextField isRequired>
      <Label>Hausnummer</Label>
    </TextField>
  </ColumnLayout>
  <ColumnLayout s={[2, 1]}>
    <TextField isRequired>
      <Label>Stadt</Label>
    </TextField>
    <TextField isRequired>
      <Label>PLZ</Label>
    </TextField>
  </ColumnLayout>
  <TextField isRequired>
    <Label>Land</Label>
  </TextField>
</ColumnLayout>
```

---

## isRequired

Um ein TextField als erforderlich zu markieren, benutze das dazugehörige
Property `isRequired`. Felder, die nicht required sind, werden als optional
gekennzeichnet.

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

<ColumnLayout m={[1, 1]}>
  <TextField isRequired>
    <Label>URL</Label>
  </TextField>
  <TextField>
    <Label>URL</Label>
  </TextField>
</ColumnLayout>
```

---

# Inhalt

## Label

Jedes TextField sollte ein passendes
[Label](/04-components/content/label/overview) besitzen. Ein gutes Label
vermittelt alle notwendigen Informationen, um das TextField korrekt auszufüllen.
Außerdem sollte es knapp (max. 2 Wörter), präzise und weder versteckt noch
auspunktiert sein.

  

**✅ Do**

Verwende ein kurzes, präzises Label, das essentielle Eingabeanforderungen kommuniziert.

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

<TextField>
  <Label>URL</Label>
  <FieldDescription>Beginnt mit https://</FieldDescription>
</TextField>
```

---

## FieldDescription

Die FieldDescription kann als optionaler Hilfstext unterhalb des TextFields
angezeigt werden, um dem Nutzer ergänzenden Informationen oder Anweisungen zu
bieten. Sie sollte sparsam verwendet werden und kann Eingabe- und
Formatierungsbeispiele liefern.

---

## Placeholder

Placeholder sind nicht accessible und dürfen daher keine Informationen
enthalten, die für das korrekte Ausfüllen des TextFields erforderlich sind. Das
größte Problem ist, dass Placeholder verschwinden, sobald Text eingegeben wird.
Darüber hinaus werden sie von manchen Assistenztechnologien nicht korrekt
erkannt und sind kognitiv schwieriger zu verarbeiten als die FieldDescription.
Statt einen Placeholder zu verwenden, ergänze das TextField mit ...

- einem [Label](/04-components/content/label/overview) für Informationen, die
  essenziell für das Verständnis der Eingabeanforderungen sind.
- einer FieldDescription, um dem Nutzer Beispiele oder Formatierungshinweise zu
  geben.

  

**⛔️ Don't**

Placeholder sollten keine essentiellen Informationen oder Formatierungshinweise enthalten.

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

<TextField placeholder="https://">
  <Label>URL</Label>
</TextField>
```

  

**✅ Do**

Verwende das [Label](/04-components/content/label/overview) für essentielle Informationen und die FieldDescription für Ergänzungen, z. B. Formatierungshinweise oder Beispiele.

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

<TextField>
  <Label>URL</Label>
  <FieldDescription>Beginnt mit https://</FieldDescription>
</TextField>
```

---

# Accessibility

Das TextField kann sowohl über die Tastatur erreicht und aktiviert werden als
auch mit Assistenztechnologien angesteuert werden. Damit auch der Inhalt
barrierefrei ist, solltest du:

- wenn möglich ein [Label](/04-components/content/label/overview) verwenden,
  welches essenzielle Eingabeanforderungen über das Label kommuniziert. Können
  die Eingabeanforderungen an das TextField durch den Kontext erschlossen
  werden, kann auf den Einsatz eines Labels verzichtet werden. In diesem Fall
  muss das TextField über **aria-labelledby** verknüpft oder über ein
  **aria-label** beschrieben werden.
- die FieldDescription nutzen, um Unterstützung, Beispiele oder
  Formatierungshilfen zu geben.
- Placeholder nicht für Inhalte verwenden, die zum Ausfüllen des TextFields
  hilfreich sind.