# Labeled field (goodtabs UI)

A label, hint, error line and required mark around any form control.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/labeled-field.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/labeled-field`

## Usage

```tsx
import { LabeledField, fieldDescribedBy } from "@/components/ui/labeled-field"
import { Input } from "@/components/ui/input"

<LabeledField id="email" label="Email" hint="We only use it to sign you in." error={error} required>
  <Input id="email" type="email" aria-invalid={!!error} aria-describedby={fieldDescribedBy("email", { hint: true, error: !!error })} />
</LabeledField>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| id | `string` |  | The control's id. Pass the same id to the control. |
| label | `ReactNode` |  | Visible label text. |
| hint | `ReactNode` |  | Help text under the control, with id `${id}-hint`. |
| error | `ReactNode` |  | Error text under the control, with id `${id}-error` and role=alert. |
| required | `boolean` | `false` | Adds the asterisk and sr-only required. |
| children | `ReactNode` |  | The control, with id and aria-describedby set by you. |

## When to use

- Around any shadcn control that needs a label: Input, Textarea, a select trigger, an OTP field
- Forms where hints and validation errors should be read by screen readers in the right order
- Settings pages with a label over each field

## When not to use

- For a checkbox or switch with its label beside it; those label themselves
- Around a group of radios or checkboxes; use a fieldset with a legend
- When the control already renders its own label

## Notes for agents

- It does not clone the child. Pass id={id} to the control yourself, and aria-describedby from fieldDescribedBy(id, { hint, error })
- Set aria-invalid on the control when error is present; the field only renders the message
- Server component: no state, so it works in server and client trees alike
- The required mark is visual plus an sr-only word; if the control also has the required attribute, screen readers may say it twice

Docs: https://ui.goodtabs.co/components/labeled-field