Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
field · base base · style base-lyraOpen under the product theme

The error keeps the hint

error adds a sentence beside the hint rather than replacing it.

Theme
Density
Text
Status
Accent theme
Accent
field-error-keeps-the-hint · base base · style base-lyraOpen under the product theme
field-error-keeps-the-hint.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
field-marking-the-exception · base base · style base-lyraOpen under the product theme
field-marking-the-exception.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
field-with-another-control · base base · style base-lyraOpen under the product theme
field-with-another-control.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
field-validating-on-submit · base base · style base-lyraOpen under the product theme
field-validating-on-submit.tsx
"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-input instead.
  • The control is an action, not an input.Use button instead.
  • Several related inputs are captured in one interaction.Use log-sheet instead.
  • You are showing a value, not collecting one.Use value instead.
  • A failed form's errors need summarising at the top.Use alert-banner instead.

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 a shadcn add copy 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.
KeyActionNotes
TabMoves focus to the controlOnly the control is focusable.
Shift+TabMoves focus back out of the controlReverse order matches visual order.
EnterAsks the control to check itself, and submits an enclosing formFocus does not move and nothing is announced.
EscapeNothingNot a popup. The key reaches a dialog.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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

AttributeConditionValue
data-slotRoot, 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-invalidOn the root and control, when error is non-empty or a constraint fails.Present with no value when invalid; absent otherwise