Field

updated

Your input's personal assistant. Label, description and error for one form control, wired to it automatically.

Demo
Profile

Shown on your public profile.

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.

Validation

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.

Horizontal

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
fielddata-orientation, data-invalid, data-disabledThe 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-setdata-invalid, data-disabledA fieldset.
field-legend—The fieldset's legend.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.23.0

    330cdd2 — Breaking: an id on Field or FieldSet lands on the field's root element, so a link to it scrolls to the field. The control's id moved to a prop of its own, controlId on Field; the label still follows it. <Field id="email"> that was meant for the input becomes <Field control-id="email">. FieldSet has no controlId: its legend names the group, and the id it used to take never reached the group.

  4. registry 0.22.0

    f29a239 — A row of a disabled RadioGroup or CheckboxGroup, or of a group inside a disabled FieldSet, looks disabled: choice-row drops its hover tint and shows a not-allowed cursor when the row's checkbox or radio is disabled, not only when its Field is, and FieldLabel dims beside a disabled checkbox or radio.

    750df71 — A Field or FieldSet inside a disabled FieldSet is disabled too, so a Slider, Rating or ColorPicker in its own Field stops taking focus and input while the form is locked. Only disabled passes down; invalid and required stay with the part that sets them.

    7fbf5ee — InputGroupButton inside a disabled Field is disabled, not only faded with its addon: it no longer takes focus or runs its click (InputTimeGroup's "Now" button changed the value of a disabled field). A disabled attribute passed to the button still wins.

    fbe99ae — InputNumber takes its text alignment from its own root through --input-number-align: a vertical InputNumber in a horizontal Field is no longer centred, an alignment class such as text-start on InputNumberInput wins, and a vertical decrement keeps its corner inside a filled Item.

  5. core 0.16.0

    f29a239 — A row of a disabled RadioGroup or CheckboxGroup, or of a group inside a disabled FieldSet, looks disabled: choice-row drops its hover tint and shows a not-allowed cursor when the row's checkbox or radio is disabled, not only when its Field is, and FieldLabel dims beside a disabled checkbox or radio.

  6. registry 0.14.0

    2add2d3 — FileUpload is built from parts, after Dice UI's anatomy: FileUpload (the files, the checks, the hidden input, paste, Field wiring and size), FileUploadDropzone (drops and a click, variant), FileUploadTrigger (the button that opens the dialog, as-child for a Button), FileUploadIcon, FileUploadTitle, FileUploadDescription, FileUploadList (layout list or grid), FileUploadItem, FileUploadItemPreview, FileUploadItemMetadata, FileUploadItemDelete and FileUploadClear, plus fileKey(file) for v-for keys. The zone that is one button is FileUploadDropzone as-child on the trigger; a zone with a Browse button holds an as-child trigger and is no tab stop itself. The props mode, layout, position, label, description, icon, file-icon, file-image, file-delete, preview, interactive and dropzone, the 14 slots and the exposed triggerEl are gone: compose the parts instead, and put a ref on the trigger for Formisch. removeFile takes the file, not an index. A trigger without a dropzone no longer takes drops.

  7. registry 0.13.0

    d9c272f — New DatePicker and DateRangePicker: an InputDate or InputDateRange with a calendar button that opens a Calendar or RangeCalendar in a popover, so a date can be typed or picked into the same v-model. <DatePicker v-model="date" /> renders the whole thing; the parts (DatePickerInput, DatePickerTrigger, DatePickerValue, DatePickerContent, DatePickerCalendar and their range twins) compose a layout of your own, including the shadcn-style outline button with DatePickerTrigger as-child. The field comes in Input's five variants and five sizes, the calendar follows the field's size unless it has its own, and inside an InputGroup the picker takes the group's frame. Picking a day closes the calendar (not when there are time segments, whose typed time a pick keeps), clicking the selected day keeps it, every month draws six weeks so the panel doesn't jump, and Alt+ArrowDown opens it from a segment. Focus on open lands on the selected day, today or the first day you can pick, never on a hidden copy from the neighbouring month. focus and blur fire once for the field, the button and the calendar together, so validate-on-blur doesn't flag the field while the calendar is open. In a Field, a button trigger takes the label, the description and the invalid state, and name submits through a hidden input: YYYY-MM-DD for a date, name[start] and name[end] for a range, with required needing both ends.

    936ab40 — New InputDate and InputDateRange: segmented date fields over Reka UI's DateField and DateRangeField, in Input's five variants and five sizes, with optional time segments, min-value/max-value, is-date-unavailable, loading and Field wiring. Inside an InputGroup they drop their own frame and take the group's variant and size. Pasting an ISO date (2025-03-14, or 2025-03-14T09:30) fills every segment, and Enter submits the form through its submit button, like a native date input. InputDateRange submits name[start] and name[end] as ISO dates, empty until that end is filled, and required needs both.

    InputTime and InputTimeRange get the same fixes. focus and blur now fire once when focus enters or leaves the field, so a form library's validate-on-blur runs; before, they never fired. Clicking the frame outside the segments focuses the first one, Enter submits the form, and changing granularity or hour-cycle after mount rebuilds the segments instead of leaving stale ones. InputTimeRange with name now submits name[start] and name[end] instead of one start - end field, which read undefined - undefined while empty and never failed required. If your server reads the old field, read the two new ones.

    11239a6 — New Rating component, on Reka UI's Rating: a row of stars to pick a score in whole, half, quarter or tenth steps. It takes size from xs to xl on the control tokens, so it lines up with a Button of the same size, and color like the other choice controls, with warning for gold stars. hoverable previews the value under a mouse or a pen but never under a finger, clearable takes the score back, and touch-target, vertical and right-to-left layouts and icon and empty-icon slots work as elsewhere.

    readonly shows an exact value, 4.3 fills the fifth star to 30%, as one picture named "Rated 4.3 out of 5", with no radios for screen readers to announce. In a Field it takes the field's id, label, description, error, invalid, required and disabled state. In a plain form, a rating with nothing picked, or cleared, submits an empty value, so native required holds until a star is picked.

    7376882 — New Calendar and RangeCalendar: month grids over Reka UI's Calendar and RangeCalendar, in Material 3 look, with the heading at the start, the arrows at the end and round days. Calendar picks one date or several; RangeCalendar picks a start and an end, fills both and draws a soft band between them, with a preview while the end is picked. Both come in five sizes on the control scale (xs to xl, 36px days at md), take color, show several months side by side with the neighbouring months' days hidden, add week numbers with week-numbers, and wire to Field: the field label and the month name label the calendar, and an invalid field turns the selection destructive. Each part is exported for a layout of your own, and a heading slot with setPlaceholder takes month and year pickers. is-date-disabled and is-date-unavailable can be swapped after mount, initial-focus skips the hidden copies of other months' days, and on reka-ui 2.10 a v-model rebuilt as a new object for the same day no longer sends the view back to its month.

    277f092 — New FileUpload: a drop zone (mode="area") or a Button (mode="button") that picks files into a File or, with multiple, a File[] v-model. Files come from the dialog, a drop or a paste, and all three go through accept, max-size and max-files, so a file of the wrong type never reaches the model even when the user picks "All files" in the dialog; whatever is turned away comes back through reject with a reason. Files show as a list or a grid of thumbnails, under the frame or inside it, with a Remove button each that moves focus to the next one. The hidden file input always holds the files on screen, so name submits them with a native form, required blocks an empty one, and a form reset puts back the starting files. A file drag is always taken, even a rejected one, so the browser never opens the file in place of the page. Five sizes on the control scale, outline, soft and subtle frames, Field wiring, and slots for every part, including triggerAttrs for your own button.

    00b6660 — New Tree: nested items to browse, select or check, over Reka UI's Tree, with TreeItem, TreeItemToggle, TreeItemCheckbox, TreeItemIcon and TreeItemLabel for rows of your own. Pass items and it renders each node's label, icon and chevron; children: [] makes a folder that loads later, and loading shows a spinner and sets aria-busy. It takes v-model (the nodes you passed in, never copies), v-model:expanded (keys), multiple, selection-behavior, checkbox with cascading checks, toggle-on-click, virtualize, name for plain form posts (required keeps an empty one from submitting), Field wiring, ghost (default) and outline variants and the five control sizes. It exposes expandAll, collapseAll and scrollToKey; getAncestorKeys and flattenTree come with it.

    The tree keeps its own selection instead of Reka UI's, which fixes a few things on the way: checking a child then its folder no longer leaves the child in the model twice, cascading checks follow getChildren to any depth and leave disabled nodes alone, a model echoed back with only leaves shows its folders checked, and a large selection no longer stalls on a deep watch. Typeahead works right after an arrow key or a Space, Tab enters on the selected row, only the selected row of a single-select tree has aria-selected, and a virtualized tree keeps focus when rows above the focused one open. Two nodes with the same key get a warning in development.

    d71e3ef — Forms with VeeValidate and Zod. New standard-schema lib item with toTypedSchema, which lets VeeValidate 4 validate with Zod 4, Valibot or any other Standard Schema: VeeValidate 4 passes a raw Zod 4 schema without a single error, and @vee-validate/zod throws on Zod 4 unions. Each issue lands at its field's path, such as emails[0].address. New examples bind every kind of control: a bug report, a select and combobox, choice groups, number, tags, pin and range inputs, a field array, an invite dialog with an error from the server, and VeeValidate's own Form and Field components through the slot.

    lib/field-context exports focusFirstInvalid(root), which moves focus to the first invalid control in page order once the errors have rendered: the input, the select trigger, the slider thumb, or the box Tab would reach in a checkbox or radio group. A control that can't take focus, such as one in a hidden tab, is skipped. It works with any validation.

    TagsInputInput no longer lets the form submit when Enter adds a tag on reka-ui 2.10, which cancels that Enter a tick late (unovue/reka-ui#2966). On reka-ui 2.11 nothing changes.

  8. registry 0.10.0

    e03458c — New InputTime and InputTimeRange: segmented time fields over Reka UI's TimeField and TimeRangeField, in Input's five variants and five sizes, with 12- or 24-hour cycles, hour, minute or second granularity, step, min-value/max-value, loading and Field wiring. Inside an InputGroup they drop their own frame and take the group's variant and size.

  9. registry 0.9.0

    3724c06 — New Combobox: a text input that filters a list of options as you type, over Reka UI's Combobox. ComboboxAnchor is Input's frame with its variants and sizes and holds ComboboxInput, ComboboxCancel and the chevron ComboboxTrigger; with as-child the anchor and trigger become a button of your own and the input moves into the list. ComboboxList, ComboboxViewport, ComboboxItem, ComboboxGroup, ComboboxLabel, ComboboxSeparator and ComboboxEmpty take Select's list styles. Single or multiple choice, wired to a surrounding Field.

    0c326fd — New InputNumber: a number field over Reka UI's NumberField with InputNumberInput, InputNumberIncrement and InputNumberDecrement parts inside one frame, in Input's variants and sizes, horizontal or vertical, with min, max, step, formatOptions and locale, wired to a surrounding Field.

    Input now exports textControlFrameVariant, the text control variants for a frame around a control, read from the control's focus, invalid and disabled state. InputGroup draws its frame from it; its radius variable is renamed from --input-group-radius to --control-radius.

    a7aad5f — New TagsInput: tags typed into one text control frame over Reka UI's TagsInput, with TagsInputItem chips drawn as badges, TagsInputItemText, TagsInputItemDelete and TagsInputInput parts, in Input's variants and sizes, with delimiter, paste, max and duplicate handling, wired to a surrounding Field.

  10. registry 0.8.0

    8c1319e — ColorPicker: ColorPicker, ColorPickerArea, ColorPickerSlider, ColorPickerField, ColorPickerPreview, ColorPickerSwatches and ColorPickerSwatch over Reka UI's colour primitives. One v-model string in hex, rgb, hsl or hsb feeds every part; the area, the sliders and the swatches work from the keyboard and read out as sliders and options; the sliders are drawn on Slider's parts with its variant, touch-target, sizes, halo and press scale, one size from xs to xl scales the parts together, and a surrounding Field supplies the label, description, error and disabled state.

  11. registry 0.7.0

    c08ee4f — PinInput: PinInput, PinInputGroup, PinInputSlot and PinInputSeparator over Reka UI's pin input, with the text control variants and sizes of Input, one-time-code autofill on by default, and label, state and error from a surrounding Field.