Field
updatedYour input's personal assistant. Label, description and error for one form control, wired to it automatically.
Installation
Usage
<script setup lang="ts">
import { Field, FieldDescription, FieldError, FieldLabel } from '@/components/ui/field'
import { Input } from '@/components/ui/input'
</script>
<template>
<Field :invalid="!!error" required>
<FieldLabel>Email</FieldLabel>
<Input v-model="email" type="email" />
<FieldDescription>Receipts go here.</FieldDescription>
<FieldError :errors="error" />
</Field>
</template>
Field wires everything up, so you never write an id by hand. The label points at the control, and screen readers read the description and the current error when the control gets focus.
invalid, disabled and required on Field reach the control and restyle the label. Required fields get an asterisk.
Need something different? Set it on the control, and it wins. Need a specific id on the control? Set control-id on Field, so the label follows. An id on Field stays on the field itself, so a link to it scrolls to the whole field.
Validation
Field doesn't judge. Bring your own validator: a form library such as Formisch or VeeValidate, a schema or a few lines of code. Pass the result to invalid and the message to FieldError.
Receipts go here.
FieldError takes a string, an array of strings or { message } objects, whatever your form library returns. Several errors become a bulleted list. No errors, nothing rendered.
On submit, move focus to the first invalid control, and its error is read out. focusFirstInvalid(form) from lib/field-context does it, in the page's order. Errors aren't announced on their own: five announcements at once help nobody.
Errors for a group
"Pick at least one" belongs to the whole group, not to one control. Wrap the radio group or checkbox group in a FieldSet: it takes invalid, disabled and required, as Field does, and has its own FieldDescription and FieldError.
Examples
Horizontal
orientation="horizontal" puts the label beside the control, which suits settings pages and checkboxes. Wrap the label and description in FieldContent to stack them.
Add responsive, and it stays stacked until the FieldGroup is at least 28rem wide.
API Reference
Every part accepts class, merged over its base classes.
Field
| Prop | Default | Type and description |
|---|---|---|
| controlId | — | stringThe control's |
| invalid | — | booleanMarks the control |
| disabled | — | booleanDisables the control and dims the label and description. |
| required | — | booleanMakes the control |
| orientation | — | "vertical" | "horizontal" | "responsive" | null
|
| Slot | Scope and description |
|---|---|
| default | {}A label, a control, and optionally a description and an error. |
FieldSet
| Prop | Default | Type and description |
|---|---|---|
| invalid | — | booleanMarks the group control inside |
| disabled | — | booleanDisables every control inside, as a native disabled fieldset does, and dims the legend. |
| required | — | booleanMarks the group control inside required. |
| Slot | Scope and description |
|---|---|
| default | {}A legend, the controls it names, and optionally a description and an error for the whole set. |
FieldLabel
| Prop | Default | Type and description |
|---|---|---|
| for | — | stringOverrides the control |
| Slot | Scope and description |
|---|---|
| default | {}The label text. |
FieldError
| Prop | Default | Type and description |
|---|---|---|
| errors | — | string | FieldErrorItem[] | nullA message, or a list of strings or |
| Slot | Scope and description |
|---|---|
| default | {}Custom content, shown instead of |
FieldContent
| Slot | Scope and description |
|---|---|
| default | {}A label and its description or error, stacked beside a checkbox in a horizontal field. |
FieldDescription
| Slot | Scope and description |
|---|---|
| default | {}Help text, added to the control's |
FieldGroup
| Slot | Scope and description |
|---|---|
| default | {}Fields, spaced evenly. Also the container that |
FieldLegend
| Slot | Scope and description |
|---|---|
| default | {}The name of the set. |
Props
- controlId
stringThe control'sid. Generated when omitted; set it here rather than on the control, so the label follows. AnidonFieldstays on its root.- invalid
booleanMarks the controlaria-invalidand colours the label. Pass whatever your form library reports.- disabled
booleanDisables the control and dims the label and description.- required
booleanMakes the controlrequiredand adds an asterisk, hidden from screen readers, to the label.- orientation
"vertical" | "horizontal" | "responsive" | nullhorizontalputs the label beside the control;responsivedoes so once the surroundingFieldGroupis at least 28rem wide.
Slots
- default
{}A label, a control, and optionally a description and an error.
Props
- invalid
booleanMarks the group control insidearia-invalid, which turns every option in it and the legend red. For errors that belong to the group, such as nothing being selected.- disabled
booleanDisables every control inside, as a native disabled fieldset does, and dims the legend.- required
booleanMarks the group control inside required.
Slots
- default
{}A legend, the controls it names, and optionally a description and an error for the whole set.
Props
- for
stringOverrides the controlidtaken from the field.
Slots
- default
{}The label text.
Props
- errors
string | FieldErrorItem[] | nullA message, or a list of strings or{ message }objects as form libraries report them. Duplicates are dropped; nothing renders when it is empty.
Slots
- default
{}Custom content, shown instead oferrors.
Slots
- default
{}A label and its description or error, stacked beside a checkbox in a horizontal field.
Slots
- default
{}Help text, added to the control'saria-describedby.
Slots
- default
{}Fields, spaced evenly. Also the container thatorientation="responsive"measures.
Slots
- default
{}The name of the set.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| field | data-orientation, data-invalid, data-disabled | The field. |
| field-label | — | The label. |
| field-content | — | A label with its description or error, stacked beside a checkbox. |
| field-description | — | Help text. |
| field-error | — | The error, rendered only when there is one. |
| field-group | — | A stack of fields. |
| field-set | data-invalid, data-disabled | A fieldset. |
| field-legend | — | The fieldset's legend. |