Skip to content

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.

Plan
You can change this later.
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

PropTypeDefaultDescription
labelstring—Visible label. Omit it for a single Checkbox or Switch that has its own `label`. Never use a placeholder as the label.
hintstring—Helper text below the control. Give the reason here when the field is disabled.
errorstring—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.
requiredbooleantrueDefault 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.
disabledboolean—Passes `disabled` to the control (and the fieldset for a group). Say why in `hint`.
readOnlyboolean—Only for TextArea (and TextField): focusable, selectable, submitted; shows a lock icon by the label.
announceErrorbooleantrueAnnounce `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.
idstringgenerated)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

Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font