Components
Field
The wrapper that gives every input a visible label, hint, error message and the wiring between them. It is why no control here can ship without a name.
Usage
pnpm dlx shadcn@latest add @opsinjs/field
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Field } from "@/components/ui/field"<Field label="Example measurement" hint="For example, 14">
<Field.Control name="example-measurement" inputMode="decimal" autoComplete="off" />
</Field>Examples
field · base base · style base-lyraOpen under the product themeThe error keeps the hint
error adds a sentence beside the hint rather than replacing it.
field-error-keeps-the-hint · base base · style base-lyraOpen under the product themeimport { Field } from "@/components/ui/field"
export default function FieldErrorKeepsTheHint() {
return (
<div className="flex w-full max-w-md flex-col gap-opsin-8">
<div className="flex flex-col gap-opsin-2">
<p className="m-0 text-opsin-footnote text-muted-foreground">Before</p>
<Field label="Example year" hint="For example, 1985">
<Field.Control
name="before"
inputMode="numeric"
autoComplete="off"
defaultValue="2087"
/>
</Field>
</div>
<div className="flex flex-col gap-opsin-2">
<p className="m-0 text-opsin-footnote text-muted-foreground">After</p>
<Field
label="Example year"
hint="For example, 1985"
error="Enter a year in the past."
>
<Field.Control
name="after"
inputMode="numeric"
autoComplete="off"
defaultValue="2087"
/>
</Field>
</div>
</div>
)
}Marking the exception
One optional field among three needed ones, marked by optionality="optional".
See Forms.
field-marking-the-exception · base base · style base-lyraOpen under the product themeimport { Field } from "@/components/ui/field"
export default function FieldMarkingTheException() {
return (
<div className="flex w-full max-w-md flex-col gap-opsin-5">
<p className="m-0 text-opsin-body text-muted-foreground">
We need all of these unless the field says otherwise.
</p>
<Field label="Example measurement" hint="For example, 14">
<Field.Control
name="example-measurement"
inputMode="decimal"
autoComplete="off"
/>
</Field>
<Field label="Example year" hint="For example, 1985">
<Field.Control
name="example-year"
inputMode="numeric"
autoComplete="off"
/>
</Field>
<Field label="Example time" hint="For example, 09:15">
<Field.Control name="example-time" autoComplete="off" />
</Field>
<Field
label="Example note"
optionality="optional"
hint="Anything you want to remember about this entry"
>
<Field.Control name="example-note" autoComplete="off" />
</Field>
</div>
)
}A control opsinjs does not ship
render on Field.Control puts the whole wiring onto a textarea and a
select.
field-with-another-control · base base · style base-lyraOpen under the product themeimport { Field } from "@/components/ui/field"
export default function FieldWithAnotherControl() {
return (
<div className="flex w-full max-w-md flex-col gap-opsin-6">
<Field
label="Example note"
optionality="optional"
hint="A few words is plenty. There is no length this has to reach."
>
<Field.Control
render={<textarea rows={3} />}
name="example-note"
autoComplete="off"
/>
</Field>
<Field
label="Example choice"
hint="Pick whichever is closest. You can change it later."
>
<Field.Control render={<select />} name="example-choice" defaultValue="">
<option value="">Choose one</option>
<option value="first">First example option</option>
<option value="second">Second example option</option>
<option value="third">Third example option</option>
</Field.Control>
</Field>
</div>
)
}Validating on submit
The default validateOn fires on submit only inside Field.Form, where an
empty field on Save shows the browser's own message. Pass error instead.
field-validating-on-submit · base base · style base-lyraOpen under the product theme"use client"
import { Button } from "@/components/ui/button"
import { Field } from "@/components/ui/field"
export default function FieldValidatingOnSubmit() {
return (
<Field.Form
className="flex w-full max-w-md flex-col gap-opsin-6"
onFormSubmit={() => {
/* Stops the browser navigating so the demo stays on the page. Base UI
calls preventDefault() on the native event once this handler is set,
so there is nothing to call here; a real product would send the
values from this handler instead. */
}}
>
<Field label="Example name" hint="For example, a nickname for this entry">
<Field.Control name="example-name" required autoComplete="off" />
</Field>
<Field
label="Example note"
hint="Anything you want to remember about this entry"
>
<Field.Control name="example-note" required autoComplete="off" />
</Field>
<Button type="submit" variant="primary" fullWidth>
Save
</Button>
</Field.Form>
)
}When to use it
Use it when
- Every input in the system, where a Field is the label guarantee.
- Any control needing a hint or error wired to it, not merely placed nearby.
- As the base for purpose-built inputs, the way ReadingInput is built.
Do not use it when
- A measurement with a unit and a plausible range.Use
reading-inputinstead. - The control is an action, not an input.Use
buttoninstead. - Several related inputs are captured in one interaction.Use
log-sheetinstead. - You are showing a value, not collecting one.Use
valueinstead. - A failed form's errors need summarising at the top.Use
alert-bannerinstead.
Accessibility
A native label points at a generated id, aria-describedby survives unmount,
aria-invalid sits on the control, and the invalid state is a glyph and a left rule,
never colour. The audit gave the error a live region, so it is announced on submit
while focus is on Save, where it was silent before. Rendered, it shows no axe
violation and no reflow at 320px, targets meet --opsin-target-minimum, and focus is
visible. pnpm run check:a11y guards role tokens and non-px sizes.
Residual items.
- The required and optional word is English only and untranslatable by prop.
- The focus ring lives in
product.css, so ashadcn addcopy without it shows no ring until you add one. - The invalid shadow drops under forced colours and print, where the glyph, words and rule still carry the state.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the control | Only the control is focusable. |
| Shift+Tab | Moves focus back out of the control | Reverse order matches visual order. |
| Enter | Asks the control to check itself, and submits an enclosing form | Focus does not move and nothing is announced. |
| Escape | Nothing | Not a popup. The key reaches a dialog. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from FieldProps in registry/bases/base/field.tsx.
label is required and there is no hideLabel. An empty label or error is
refused with a development warning. Without a Field.Form ancestor the default
validateOn checks on Enter alone.
Prop
Type
Generated from FieldControlProps in registry/bases/base/field.tsx.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | Root, label and control always; optionality, hint and error only when that part renders; Field.Form where mounted. | field, field-label, field-optionality, field-hint, field-error, field-control, field-form |
| data-invalid | On the root and control, when error is non-empty or a constraint fails. | Present with no value when invalid; absent otherwise |