BridgeHandbookDraft
For agents
Menu
ExperimentalmoleculeInputs

Field

A label, a control, help text and an error, tied together.

import { … } from "@brdgapp/ui/components/field"

Usage

Field holds one form question: its label, the control (an Input, a TagInput), help text and the error, tied together so they're read as one. FieldGroup stacks fields 16px apart. The usual mistake is wiring labels and errors by hand and missing one, so a screen reader hears a box with no name or an error with no field.

When to use

  • Every question in a form: Add a network, Edit contact, settings that save with a button.

When not to use

  • For a setting that applies the moment it's flipped. Use a Switch with its label beside it. Use Switch instead.
  • For a search box above a list. Use SearchInput instead.

Every control has a name

Every control says what it does to a screen reader. An icon-only button carries an aria-label naming the action ("Close", not "X"); a group of filters or a table has a name; a tooltip is never the only name.

Anatomy

Adds the logo and links to the network page.

Enter a domain, like lanternfield.example

  1. Label. 14px medium --text-primary, above the control. Sentence case, no colon.

  2. Optional mark. “(optional)” in muted text after the label, on fields people can skip. Required fields get no mark.

  3. Control. The Input, TagInput or other control, 6px under the label.

  4. Help text. 12px --text-muted under the control: what the value is for.

  5. Error. 12px --danger-text with a small alert icon, under the control. Says how to fix it.

Examples

Add a network

Press Add network with the name empty, or type “lanternfield” as the website and press Tab. Errors appear when you leave a field or save, and go as soon as the value works.

Add a network

Adds the logo and links to the network page.

An error

Under the field, with an icon, saying how to fix it.

Enter a domain, like lanternfield.example

States

StateWhat happens
DefaultLabel, control, help text.
Invalidinvalid on the Field: the control turns red and FieldError shows its message.
Disableddisabled on the Field disables the control and dims the label.

Behavior

  • Built on Base UI Field: the label points at the control, and help text and error are linked with aria-describedby. No ids to write.
  • You decide when a value is wrong; Field shows it. Follow the Forms pattern: check a field when people leave it and on Save, never while they type, and clear the error as soon as the value works.
  • FieldError renders only when it has text, so it can always be in place.

Do and don't

Do

Mark the fields people can skip with optional.

Don't

Put a red asterisk on the required ones.

Do

Say how to fix it: “Enter a domain, like lanternfield.example”.

Don't

Say “Invalid” or “This field is required”.

Content

  • Label: a short noun, sentence case, no colon. “Network name”.
  • Help text: what it's for, before the mistake. “Adds the logo and links to the network page.”
  • Error: the fix, with an example that works.

Accessibility

  • Every control has a visible label tied to it; Field does the tying.
  • Help text and the error are read with the control.
  • On Save with problems, move focus to the first field that needs fixing.
KeysAction
TabMoves to the next field, and checks the one you left.

API reference

Field

One question. Built on Base UI Field.

PropTypeDefaultDescription
invalidboolean—The value has a problem: the control turns red and FieldError shows.
disabledboolean—Disables the control and dims the label.
namestring—The form name of the control.
classNamestring—Layout only.

FieldLabel

The visible label, tied to the control.

PropTypeDefaultDescription
optionalbooleanfalseAdds “(optional)” after the label.

FieldDescription

Help text under the control, read with it.

PropTypeDefaultDescription

FieldError

The error under the control. Renders only when it has text.

PropTypeDefaultDescription
childrenReactNode—The message: how to fix it.

FieldGroup

Stacks fields 16px apart.

PropTypeDefaultDescription

Lineage

What it's built from and where it's used, read from the code. When you change it, check these too.

Built from
Nothing else in the package
Used by components
None
Used in patterns
Forms and validation
Used in templates
None

Sources

  • shadcn field (Base UI style), pulled with npm run ui-add, cut down to Field, FieldLabel, FieldDescription, FieldError and FieldGroup, and built on Base UI Field.
  • Forms and validation pattern; decisions in 01-decisions.md (optional fields marked, check on leave and on Save). Label look picked by Aman 2026-11-03.
  • Bridge OS network-entry-modal.tsx → FieldError (icon + 12px text).