ui/components/field

Field

Form field primitives that wire labels, controls, descriptions, and validation messages without owning the actual input component.

Preview

tsx

1 import { Field } from "@/components/ui/field";2 import { Input } from "@/components/ui/input";3 4 export default function FieldInput() {5   return (6     <Field invalid required>7       <Field.Label>Email</Field.Label>8       <Field.Control>9         <Input placeholder="you@example.com" />10       </Field.Control>11       <Field.Description>Used for review notifications.</Field.Description>12       <Field.Error>Email is required.</Field.Error>13     </Field>14   );15 }16

Installation

$pnpm exec dgadd add ui/field

[Installs to]src/components/ui/field[Item]ui/field

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { Field } from "@/components/ui/field";2 import { Input } from "@/components/ui/input";3 4 export default function FieldInput() {5   return (6     <Field invalid required>7       <Field.Label>Email</Field.Label>8       <Field.Control>9         <Input placeholder="you@example.com" />10       </Field.Control>11       <Field.Description>Used for review notifications.</Field.Description>12       <Field.Error>Email is required.</Field.Error>13     </Field>14   );15 }16

Examples

Valid, invalid, disabled

Preview

tsx

1 import { Field } from "@/components/ui/field";2 import { Input } from "@/components/ui/input";3 4 export default function FieldStates() {5   return (6     <div className="grid max-w-2xl gap-4 sm:grid-cols-3">7       <Field required>8         <Field.Label>Email (valid)</Field.Label>9         <Field.Control>10           <Input defaultValue="you@example.com" />11         </Field.Control>12         <Field.Description>Used for review notifications.</Field.Description>13       </Field>14       <Field required invalid>15         <Field.Label>Email (invalid)</Field.Label>16         <Field.Control>17           <Input defaultValue="you@" />18         </Field.Control>19         <Field.Description>Used for review notifications.</Field.Description>20         <Field.Error>Enter a full email address.</Field.Error>21       </Field>22       <Field disabled>23         <Field.Label>Workspace</Field.Label>24         <Field.Control>25           <Input defaultValue="diffgazer/main" />26         </Field.Control>27         <Field.Description>Locked while a review is running.</Field.Description>28       </Field>29     </div>30   );31 }32

Checkbox and Select

Preview

tsx

1 import { Checkbox } from "@/components/ui/checkbox";2 import { Field } from "@/components/ui/field";3 import {4   Select,5   SelectContent,6   SelectItem,7   SelectTrigger,8   SelectValue,9 } from "@/components/ui/select";10 11 export default function FieldControls() {12   return (13     <div className="flex max-w-sm flex-col gap-4">14       <Field>15         <Field.Label>Merge when all checks pass</Field.Label>16         <Field.Control>17           <Checkbox defaultChecked />18         </Field.Control>19         <Field.Description>Clicking the label toggles the checkbox.</Field.Description>20       </Field>21       <Field required>22         <Field.Label>Base branch</Field.Label>23         <Field.Control>24           <Select defaultValue="main">25             <SelectTrigger>26               <SelectValue placeholder="Select a branch..." />27             </SelectTrigger>28             <SelectContent>29               <SelectItem value="main">main</SelectItem>30               <SelectItem value="develop">develop</SelectItem>31               <SelectItem value="release/v2">release/v2</SelectItem>32             </SelectContent>33           </Select>34         </Field.Control>35         <Field.Description>Reviews compare against this branch.</Field.Description>36       </Field>37     </div>38   );39 }40

Form integration

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Field } from "@/components/ui/field";5 import { Input } from "@/components/ui/input";6 7 export default function FieldForm() {8   const [email, setEmail] = useState("");9   const [submitted, setSubmitted] = useState(false);10   const isInvalid = submitted && email.trim() === "";11 12   return (13     <form14       noValidate15       className="flex max-w-sm flex-col gap-3"16       onSubmit={(event) => {17         event.preventDefault();18         setSubmitted(true);19       }}20     >21       <Field required invalid={isInvalid}>22         <Field.Label>Email</Field.Label>23         <Field.Control>24           <Input25             name="email"26             value={email}27             placeholder="you@example.com"28             onChange={(event) => setEmail(event.currentTarget.value)}29           />30         </Field.Control>31         <Field.Description>Used for review notifications.</Field.Description>32         <Field.Error>Email is required.</Field.Error>33       </Field>34       <button35         type="submit"36         className="w-fit border border-border px-3 py-1.5 text-xs font-bold uppercase"37       >38         Save39       </button>40     </form>41   );42 }43

API Reference

Field

Name	Type	Default	Description
controlId	string	—	Override the auto-generated id used by the wrapped control, label, description, and error.
invalid	boolean	false	Marks the control as invalid; sets aria-invalid and surfaces Field.Error in aria-describedby.
required	boolean	—	Marks the control as required and shows a required indicator next to Field.Label. The indicator is muted at rest and resolves to the error hue only while the field is invalid, so a resting form carries no error-hue marks. This remains authoritative when the child sets required={false}.
disabled	boolean	—	Disables the control and applies data-disabled to the field root. This remains authoritative when the child sets disabled={false}.

Field.Label

Name	Type	Default	Description
htmlFor	string	controlId	Override the htmlFor target. Defaults to the Field's resolved control id (a consumer id on the control child wins). For div-based controls such as Checkbox and Radio, clicking the label also focuses and activates the control.
id	string	—	Override the auto-generated label id used for aria-labelledby on the control.

Field.Control

Name	Type	Default	Description
childrenrequired	ReactElement	—	Single child control. Field clones it with id, disabled, required, aria-invalid, aria-describedby, and aria-labelledby. If the child supplies its own id, that id wins and Field.Label's htmlFor follows it.

Field.Description

Name	Type	Default	Description
children	ReactNode	—	Helper text. Returns null when empty so aria-describedby stays clean, and renders screen-reader-only while the field is invalid and Field.Error has content.

Field.Error

Name	Type	Default	Description
children	ReactNode	—	Validation message. Renders and is surfaced in aria-describedby only while Field is invalid.

Accessibility

Notes

Form Contract

Field.Control clones one control element and applies id, required, disabled, aria-invalid, and aria-describedby from Field.Root. A disabled Field.Root remains authoritative even if the child explicitly sets disabled={false}. A required Field.Root remains authoritative even if the child explicitly sets required={false}. Use Field.Control with Input, Textarea, Select, or another control that accepts those props. A consumer id on the control child wins: Field keeps the child's own id and points Field.Label's htmlFor at it. Slots register through context, so wrapping Field.Label, Field.Description, or Field.Error in a layout element keeps the ARIA wiring intact.

One Helper Slot

Field.Description and Field.Error share one visible row. While the field is invalid and Field.Error has content, the description renders screen-reader-only and the error takes its place, so field height does not depend on validity and a form validating on blur does not push the input the user is correcting. The description keeps its id and its place in aria-describedby, which lists the error first so the problem is announced before the hint.

InputGroup vs Field

InputGroup is only a decorated input shell for prefix and suffix content. Plain text affixes are aria-hidden decoration; interactive affixes need explicit labels. Field is the form wrapper for label, helper text, and error wiring.

Source

Install via CLI: pnpm exec dgadd add ui/field.

Highlighted source loads after this disclosure opens. Browse the source repository.

Field

Installation

Usage

Examples

Valid, invalid, disabled

Checkbox and Select

Form integration

API Reference

Field

Field.Label

Field.Control

Field.Description

Field.Error

Accessibility

Notes

Form Contract

One Helper Slot

InputGroup vs Field

Source

View component source (16 files)