# 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.

## Overview

# Playground

Verwende `<TextField />`, um ein TextField anzuzeigen. Nutze ein `<Label />`, um
Informationen zu vermitteln, die das Verständnis der Eingabeanforderungen
erleichtern. Weiterführende Informationen (z. B. Formatierungshinweise) können
über die `<FieldDescription />` ergänzt werden.

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

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

---

# Disabled

Wenn das TextField disabled ist, kann nicht mit ihm interagiert werden. Sobald
die Ursache für die Deaktivierung behoben ist, kann das TextField wieder normal
verwendet werden.

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

<TextField isDisabled>
  <Label>URL</Label>
</TextField>
```

---

# Validierung

Um das textField zu validieren, stehen folgende Properties zur Verfügung:

- `isRequired` für Pflichtfelder.
- `validate` für eigene Validierungen.
- HTML Input Properties wie `type="email"`, `minLength`.

Wenn die Benutzereingabe nicht den Anforderungen entspricht, wird das TextField
invalidiert. Mittels `<FieldError />` kann eine Fehlermeldung angezeigt werden.

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

<TextField isInvalid defaultValue="hello">
  <Label>URL</Label>
  <FieldError>Das ist keine URL</FieldError>
</TextField>
```

---

# Value

Standardmäßig ist der Value eines TextFields leer. Es ist möglich dem TextField
eine uncontrolled `defaultValue` mitzugeben. Es kann auch ein controlled `value`
für das TextField gesetzt werden, um dieses über `onChange` zu updaten.

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

<TextField defaultValue="https://mittwald.de">
  <Label>URL</Label>
</TextField>
```

---

# Input Properties

Das TextField unterstützt die Standard-Properties eines HTML `<input />` Feldes.
(s. [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input))

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

<TextField name="email" type="email">
  <Label>E-Mail</Label>
</TextField>
```

---

# Character Count

Über das `showCharacterCount` Property wird eine FieldDescription hinzugefügt,
die aktuelle Anzahl der Zeichen und, falls angegeben, die maximale Zeichenanzahl
anzeigt.

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

<TextField showCharacterCount maxLength={10}>
  <Label>Benutzername</Label>
</TextField>
```

---

# Passwort

TextFields mit `type="password"` erhalten automatisch einen Button zum ein- und
ausblenden des Passworts.

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

<TextField type="password">
  <Label>Passwort</Label>
</TextField>
```

---

# Kombiniere mit ...

## Align

Benutze die [Align](/04-components/structure/align/overview) Komponente, um
einem Button neben deinem TextField zu platzieren.

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

<Align>
  <TextField>
    <Label>Weiterleitungsziel</Label>
  </TextField>
  <Button>Hinzufügen</Button>
</Align>
```

## ContextualHelp

Benutze die [ContextualHelp](/04-components/overlays/contextual-help/overview)
Komponente, wenn du weitere Informationen bereitstellen möchtest, und diese zu
lang für die FieldDescription sind.

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

<TextField>
  <Label>
    URL
    <ContextualHelpTrigger>
      <Button />
      <ContextualHelp>
        <Heading>Weitere Informationen</Heading>
        <Text>
          Hier gibt es weitere Informationen, die zu lang
          für die FieldDescription sind.
        </Text>
      </ContextualHelp>
    </ContextualHelpTrigger>
  </Label>
</TextField>
```

## React Hook Form

```tsx
import {
  Label,
  Section,
  TextField,
} from "@mittwald/flow-react-components";
import { useForm } from "react-hook-form";
import {
  Form,
  SubmitButton,
  typedField,
} from "@mittwald/flow-react-components/react-hook-form";
import { sleep } from "@/content/04-components/actions/action/examples/lib";

export default () => {
  const form = useForm<{ url: string }>();
  const Field = typedField(form);

  return (
    <Section>
      <Form form={form} onSubmit={sleep}>
        <Field
          name="url"
          rules={{
            required: "Bitte gib eine URL ein",
          }}
        >
          <TextField>
            <Label>URL</Label>
          </TextField>
        </Field>
        <SubmitButton>Speichern</SubmitButton>
      </Form>
    </Section>
  );
}
```

## Button

Du kannst einen Button zum TextField hinzufügen, um benutzerdefinierte Aktionen
auszuführen.

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

<TextField>
  <Label>Label</Label>
  <Button aria-label="Custom Button">
    <IconStar />
  </Button>
</TextField>
```