Field · Clinia UI

When to use

Wrap any form control with its label, description and error, so the three stay together and line up across the form.
Group several fields with FieldGroup, or a set of checkboxes or radio buttons with FieldSet and FieldLegend.

When not to use

A lone control with a label and nothing else: Label is enough.
An input with icons or buttons inside its border: put an Input Group inside the Field.

Install

npx shadcn@latest add @clinia/field

Require single sign-on

Marketing (Sera)

Require single sign-on

Anatomy

1Fielddata-slot="field"role=group · flex-col
2Labeldata-slot="field-label"text-sm · font-medium
3Controldata-slot="input"border-input · border-destructive when invalid
4Descriptiondata-slot="field-description"text-sm · text-muted-foreground
5Error (when invalid)data-slot="field-error"text-sm · text-destructive

Clinia rules

vertical (default) stacks label, control, description and error. horizontal puts the label beside a checkbox or switch. responsive switches at the FieldGroup container's breakpoint.
data-invalid on the Field turns its label and error text destructive. FieldError only renders when it has a message.
The description says what the value is for or how it's formatted (Shown to everyone you invite.). Keep hints out of the placeholder.
A choice card is a FieldLabel wrapped around a horizontal Field with a radio or checkbox. The checked card takes a Trust border over a bg-accent/15 tint, and the others take the ink tint on hover.
On a marketing site, the Sera field matches the forms on clinia.com: a 42px box with an input border and 8px corners, a 16px value, and the label above it in 16px sentence case. Focus takes the ring border and halo, as in product apps.

Do and don't

Do put the hint in the description, under the control.

Don't hide the hint in the placeholder, where it disappears on typing.

Do keep text fields vertical, with the label above.

Billing email

Don't squeeze a text field into a horizontal row.

States: product (Luma)

with description

invalid

disabled

choice cards

Starter

Up to three workspaces.

Pro

Unlimited workspaces and single sign-on.

Toggle the site theme to review both themes.

States: marketing (Sera)

with description

invalid

disabled

choice cards

Starter

Up to three workspaces.

Pro

Unlimited workspaces and single sign-on.

Toggle the site theme to review both themes.

Accessibility

Built in

Mark the field data-invalid and the control aria-invalid together: the first styles the label, the second the control and its focus ring.
Field renders role="group". FieldError renders role="alert", so a new message is announced when it appears.

Your responsibility

Link the parts yourself: FieldLabel needs htmlFor set to the control's id, and the control needs aria-describedby pointing at the FieldDescription and FieldError ids.
Name a FieldSet with a FieldLegend, so the question is read with each option.
Don't show an error before the user has had a chance to answer. Validate on blur or on submit.

How to test

Click each label: focus moves to its control.
Tab into a field with a description: a screen reader reads the label, then the description.
Submit with an error: the message appears under the control, is announced, and is read again when the field gets focus.
Narrow the window with a responsive field: the label moves above the control and nothing overlaps.

API

Field

Prop	Values	Default	Description
orientation	`verticalhorizontalresponsive`	`vertical`	`horizontal` puts the label beside the control, for checkboxes and switches. `responsive` switches at the container's breakpoint.

FieldError

Prop	Values	Default	Description
errors	`({ message?: string; } \| undefined)[]`	–	Validation errors, such as a form library's. Duplicates show once and several messages render as a list; children replace them.

FieldLegend

Prop	Values	Default	Description
variant	`labellegend`	`legend`	`label` sizes the legend like a field label.

All other props come from the native div element.