FormField
Label, hint and error for any Shavin control that has none of its own: TextArea, Select, Combobox, DatePicker, TimePicker, Checkbox, Switch, RadioGroup, CheckboxGroup. TextField already has label/hint/errorMessage: use it alone.
// Plain markup
import { FormField } from "@shavin/ui";States
Default with a hint, error (icon + text, replaces the hint), success, read-only and disabled with the reason in the hint.
Shown on your public profile.
Choose a time zone.
Handle is available.
Set by your workspace admin.
Available on the Pro plan.
Component Source
<FormField label="Bio" hint="Shown on your public profile." required={false}>
<TextArea rows={3} />
</FormField>
<FormField label="Time zone" error="Choose a time zone.">
<Select options={zones} />
</FormField>
<FormField label="Handle" hint="Handle is available." status="success">
<TextArea rows={1} defaultValue="avin" />
</FormField>
<FormField label="Billing note" hint="Set by your workspace admin." readOnly>
<TextArea rows={2} defaultValue="Invoices go to finance@example.com" />
</FormField>
<FormField label="Custom domain" hint="Available on the Pro plan." disabled>
<Select options={zones} />
</FormField>Single-line text: TextField alone
TextField already has label, hint and errorMessage. Do not wrap it.
We send receipts here.
Component Source
<TextField label="Email" type="email" hint="We send receipts here." errorMessage={errors.email} />Groups and settings rows
RadioGroup and CheckboxGroup get a fieldset and legend. A Switch keeps its own label; horizontal puts the label left from md up.
Sent on Mondays.
Component Source
<FormField label="Plan" hint="You can change this later.">
<RadioGroup defaultValue="free">
<Radio value="free" label="Free" />
<Radio value="pro" label="Pro" />
</RadioGroup>
</FormField>
<FormField label="Weekly summary" orientation="horizontal" hint="Sent on Mondays.">
<Switch aria-label="Weekly summary" />
</FormField>Validation timing
- Validate on blur the first time, then on change once the field has an error.
- On submit, validate everything, show a FormErrorSummary at the top and keep each field's error.
- Keep Submit enabled while the user fills the form; use Button loading only while the request runs.
- Messages say what is wrong and how to fix it: "Enter an email like name@company.com".
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | — | Visible label. Omit it for a single Checkbox or Switch that has its own `label`. Never use a placeholder as the label. |
| hint | string | — | Helper text below the control. Give the reason here when the field is disabled. |
| error | string | — | Error message: marks the control invalid (aria-invalid), replaces the hint, icon + text. |
| status | "default" | "success" | — | `success` shows a check icon and the hint in the success colour ("Email verified"). Use sparingly. |
| required | boolean | true | Default true (false for a single Checkbox or Switch, where required means "must be on"). Optional fields (false) show "Optional" after the label; required ones get no asterisk. |
| disabled | boolean | — | Passes `disabled` to the control (and the fieldset for a group). Say why in `hint`. |
| readOnly | boolean | — | Only for TextArea (and TextField): focusable, selectable, submitted; shows a lock icon by the label. |
| announceError | boolean | true | Announce `error` (polite) once when it first appears. Default true. |
| size | "sm" | "md" | "lg" | — | One size for every field in a row; passed to Select and Combobox, ignored by the others. |
| id | string | generated) | id for the control (default generated). Links the label and the FormErrorSummary item. |
| children* | ReactElement | — | Exactly one Shavin control: TextArea, Select, Combobox, DatePicker, TimePicker, Checkbox, Switch, RadioGroup or CheckboxGroup. |
| orientation | "vertical" | "horizontal" | "vertical" | — |
* required