# Field

> Puts a label, a hint and an error message around one form control.

A field puts a label above a form control, a one-sentence hint below it and, when the backend refuses the value, the backend's error message.

## When to use

- Wrap every form control that people fill in: Input, Textarea, Select, Combobox, Input OTP.
- Use `FieldSet` with a `FieldLegend` to group controls that answer one question, such as a Radio Group.
- Use the `horizontal` orientation only for a Switch or a Checkbox, with the control before its label.
- Don't write error messages in the client. The backend validates every field and returns the message; the client only disables the submit button until the required fields have a value.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/field/_

## Anatomy

1. Label
2. Control, red border while invalid
3. Hint
4. The backend's error message

1. **Label** (`FieldLabel`): above the control, in `foreground`. It turns `destructive` when the field is invalid.
2. **Control**: the input, textarea or other control, with `aria-invalid` while its value is refused.
3. **Hint** (`FieldDescription`): one practical sentence in `muted-foreground`.
4. **Error** (`FieldError`): the backend's message in `destructive`, with `role="alert"`.

Point the control at the hint and the error with `aria-describedby`, so screen readers read both. The field does not add the ids for you.

## Variants

| Orientation | Use it for |
| --- | --- |
| `vertical` (default) | Every text control: label above, hint and error below. |
| `horizontal` | A Switch or a Checkbox: the control on the left, the label and hint on the right. |

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `orientation` on `Field` | `orientation` on `Field` | separate widgets (`ShadSwitch` has its own `label`) | `vertical` / `horizontal` | `vertical` | Places the label above or beside the control. |
| `data-invalid` on `Field` | `data-invalid="true"` on `Field` (a bare `data-invalid` renders empty and does not match) | `forceErrorText` | boolean / text | none | Marks the field as refused. |
| `FieldLabel htmlFor` | `FieldLabel for` | `label` | text | none | Names the control. |
| `FieldDescription` | `FieldDescription` | `description` | text | none | The one-sentence hint. |
| `FieldError` | `FieldError` | `forceErrorText` | text | none | The backend's error message. |
| `FieldSet`, `FieldLegend` | `FieldSet`, `FieldLegend` | a `Text` heading over the group | none | none | Groups controls that answer one question. |

## Code

**React**
```tsx
import { useId } from "react"
import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

export default function FieldDemo() {
  const id = useId()
  return (
    <FieldGroup className="w-full max-w-sm">
      {/* The error comes from the backend; the client only shows it. */}
      <Field data-invalid>
        <FieldLabel htmlFor={`${id}-title`}>Judul lagu</FieldLabel>
        <Input
          id={`${id}-title`}
          aria-invalid
          aria-describedby={`${id}-title-hint ${id}-title-error`}
        />
        <FieldDescription id={`${id}-title-hint`}>Tulis sesuai sampul rilis.</FieldDescription>
        <FieldError id={`${id}-title-error`}>Judul lagunya belum diisi.</FieldError>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${id}-notes`}>Catatan</FieldLabel>
        <Textarea id={`${id}-notes`} aria-describedby={`${id}-notes-hint`} />
        <FieldDescription id={`${id}-notes-hint`}>Opsional, untuk tim rilis.</FieldDescription>
      </Field>
    </FieldGroup>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { useId } from "vue"
import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

const id = useId()
</script>

<template>
  <FieldGroup class="w-full max-w-sm">
    <!-- The error comes from the backend; the client only shows it. -->
    <Field data-invalid="true">
      <FieldLabel :for="`${id}-title`">Judul lagu</FieldLabel>
      <Input :id="`${id}-title`" aria-invalid="true" :aria-describedby="`${id}-title-hint ${id}-title-error`" />
      <FieldDescription :id="`${id}-title-hint`">Tulis sesuai sampul rilis.</FieldDescription>
      <FieldError :id="`${id}-title-error`">Judul lagunya belum diisi.</FieldError>
    </Field>
    <Field>
      <FieldLabel :for="`${id}-notes`">Catatan</FieldLabel>
      <Textarea :id="`${id}-notes`" :aria-describedby="`${id}-notes-hint`" />
      <FieldDescription :id="`${id}-notes-hint`">Opsional, untuk tim rilis.</FieldDescription>
    </Field>
  </FieldGroup>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

class FieldDemo extends StatelessWidget {
  const FieldDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 384),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.stretch,
        spacing: 24,
        children: [
          // The error comes from the backend; the field only shows it.
          ShadInputFormField(
            id: 'title',
            label: const Text('Judul lagu'),
            description: const Text('Tulis sesuai sampul rilis.'),
            forceErrorText: 'Judul lagunya belum diisi.',
          ),
          ShadTextareaFormField(
            id: 'notes',
            label: const Text('Catatan'),
            description: const Text('Opsional, untuk tim rilis.'),
          ),
        ],
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/field.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/field.json
```

## Accessibility

- Every control has a visible label tied to it with `htmlFor` / `for`.
- An invalid control has `aria-invalid="true"` and an `aria-describedby` that lists the hint id and the error id.
- The error has `role="alert"`, so it is announced when it appears.
- A `FieldSet` names its group with its `FieldLegend`.
