You're in the Library

Field

Wires a visible label, an optional description and an error message to one form control. Ids, aria-describedby, aria-invalid and validation timing are handled by Base UI Field.
Stable
Edit

Preview appears after the next Storybook update.

Field example
<Field />
Rendered with the real componentFrom the code
Light
Dark

When to use

Use it for

  • Around every Input, Textarea, Select, Combobox, NumberField or Slider that does not take a label prop itself.
  • To show a server-side error next to the right control (error prop, or Form errors by name).
  • description for what the user needs before typing: format, limits, why you ask.

Not for

  • Checkbox and Switch: they carry their own label next to the control.
  • A group of checkboxes or radios: use CheckboxGroup or RadioGroup, which render a fieldset and legend.

Do and don't

Every example is rendered with the real component, so it always matches what ships.

Paste the link from Share, Copy link.

Enter a Figma design link.
Do

Description before, error after

The description answers questions before typing; the error appears under the control, where the eye already is.

Don't

Placeholder as the label

It disappears on the first keystroke and has low contrast. Keep a visible label.

Accessibility

  • The label is a native <label> bound to the control: clicking it focuses the control.
  • description and error are linked through aria-describedby; an error also sets aria-invalid on the control.
  • Errors carry an icon and text, never color alone (WCAG 1.4.1).
  • required shows an asterisk (hidden from screen readers) and sets the native required attribute, which is announced.
  • hideLabel keeps the label for assistive tech; use it only when the context labels the field visually (a search bar with an icon).

Content guidelines

  • Labels are nouns in sentence case, no colon: "Repository", not "Repository:".
  • Errors name the problem and the fix: "Repository not found. Check the owner and the name."
  • Do not repeat the label in the description.

From the code Generated from the component, not editable here.

Anatomy and tokens

Read from packages/react/src/components/Field/Field.module.css at build time. Every value is a token: open one to see its alias chain in both themes.

16 tokens5 semantic or component, change with theme and brand11 from the shared scales

Motion and interaction

Field animates on hover. Try it in the preview at the top.

WhenWhat changesDurationEasing
HoverBordermotion.duration.instant75 msmotion.easing.standardsettles in place

With reduced motion turned on, every change happens at once.

From the code Generated from the component, not editable here.

Props

Parsed from the TypeScript types in packages/react/src/components/Field/Field.tsx, so this table cannot drift from the code. It also accepts every native <div> attribute except onChange.

PropTypeDefaultDescription
labelrequiredReactNodenoneVisible label. Required: placeholders are not labels.
childrenrequiredReactNodenoneThe control: Input, Textarea, Select, Combobox, NumberField, Slider.
descriptionReactNodenoneHelp shown under the label, before the control: format, constraints, privacy notes.
errorReactNodenoneError message. When set, the field is invalid and the message is announced through aria-describedby. Leave it unset to show the browser's validation message after a failed submit.
requiredbooleanfalseMarks the control as required (adds `required` to our controls and a visual marker to the label).
disabledbooleannoneNo description in the code yet.
namestringnoneName used by Form for submit values and server errors.
validate(value: unknown) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>noneCustom validation. Return an error string (or strings) to mark the field invalid.
validationMode'onSubmit' | 'onBlur' | 'onChange'noneWhen validation runs. Default `onSubmit` (inherits Form).
hideLabelbooleanfalseVisually hide the label (it stays the accessible name). Use only when the context labels the field, like a search bar.

Comes with useFieldContext, each accepting native <div> attributes.

Playground

Change the props and see the real Field update. Controls are generated from the TypeScript props; nothing here changes the system.

Code for these props
<Field
  validationMode="onSubmit"
  label="Repository"
  description="Owner and name, like acme/design-tokens."
/>

validationMode

Workbench

For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Field in Storybook).

Embed Storybook stories here (5)

Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.

Default

Invalid

Required

Disabled

AllStates

From the code Generated from the component, not editable here.

Changelog

  • Breaking

    Bridge brand moves to the "Field Guide" direction: white content, ink text, Harbor zones and Deep Harbor as the one strong color, Fraunces headings over Instrument Sans text, rounder radii

    v1.0.0, Nov 11, 2026

  • New

    A bridge.config.json field this version does not know is warned about and left alone, never fatal: a config written for a newer Bridge (a product's design copy, a new setting) still loads in an older CLI, workflow or MCP server

    v1.0.0, Nov 11, 2026

  • New

    Component change requests: composeRequestIssue, parseRequestIssue, requestStatus, requestBrief, Jira field mapping, GitHub issue methods, and an integrations block in bridge.config.json

    v1.0.0, Nov 11, 2026

  • New

    The agent mark of Avatar kind="agent" (and avatarHtml({ kind: 'agent' })) is now the Field Guide robot from the landing page: a rounded head with an antenna, two dot eyes, a smile, side ears and two legs, drawn as one round-cap stroke in currentColor with no fill, so it keeps the tile contrast in light and dark and reads at the xs size (16px mark)

    v1.0.0, Nov 11, 2026

  • New

    Textarea gets appearance="inline" for editing existing text in place: no border, no resize handle, the surrounding font, size and line height, a height that fits the content (field-sizing: content, measured without moving the page where it is not supported), a fill and hairline on hover and the DS focus ring on focus

    v1.0.0, Nov 11, 2026

  • New

    Forms: Field (label, description, error wired by Base UI Field) and Input rebuilt on it (prefix, suffix, sizes; label, hint and error props kept)

    v1.0.0, Nov 11, 2026

  • New

    A new homepage at "/", ported from the validated test page: drag the bridge to keep what your exploration added; "Start it in Bridge", "Ship it everywhere at once" and "One system everyone can trust", each step drawn as an animated Field Guide illustration; "Decide in seconds" for the design system lead; "How Bridge compares" (a short table, every feature on demand); the questions teams ask; and the Horizon closing

    v1.0.0, Nov 11, 2026

  • Fix

    withRepoTokenPaths binds a measured field whose declaration is a variable alone (var(--cds-button-primary, #0f62fe)) to the written token of its chain, so a design system measured without token files gets its colors and type bound to variables

    v1.0.0, Nov 11, 2026

  • Fix

    Measure: a part's box-shadow becomes a shadow field (drop and inner shadows, transparent rings left out), drawn as Figma effects by the plugin; and a part a transform moves or scales (a progress indicator slid left with translateX) sits where and as big as it is drawn, out of the flow, instead of where the layout would put it

    v1.0.0, Nov 11, 2026

  • Fix

    Combobox: a chip cut by the field width shows its full value on hover (title)

    v1.0.0, Nov 11, 2026

  • Fix

    Combobox: the listbox takes the field's name (its label, aria-label or aria-labelledby), so it is never an anonymous list, including while it closes

    v1.0.0, Nov 11, 2026

  • Fix

    Add a product opens on one question, "Which product does your team design for?", with two choice cards and their Field Guide drawings: "It's already built" (pick your product, or "Find it on GitHub" when Bridge sees none, with "Ask a developer" copying a ready message) and "It's a new product" (Bridge sets it up with your library)

    v1.0.0, Nov 11, 2026

  • Fix

    It's a new product: no Where field and no address line any more

    v1.0.0, Nov 11, 2026

  • Fix

    Studio: page headers drop their drawing, so the primary action sits at the end of the title line again and the header stays compact; Field Guide drawings show at once, with no draw-in

    v1.0.0, Nov 11, 2026

  • Fix

    Studio Tokens: a page header and one toolbar row (filter field "Filter N tokens", type chips with counts, one Options menu for collections, usage, brand and modes, columns and exact match, then New token), and the table at full width with Name, Light and Dark

    v1.0.0, Nov 11, 2026

  • Fix

    Pull no longer hides every component when one value in component-specs.json has a shape the plugin does not read: that field is listed with the others that cannot be bound ("update DS Bridge") and the rest pull as usual

    v1.0.0, Nov 11, 2026

  • Fix

    Community art in the Field Guide direction (Fraunces, Harbor zone, Deep Harbor), with fresh screenshots of the plugin (595 variables) and Bridge Studio

    v1.0.0, Nov 11, 2026

  • Fix

    Settings: a saved GitHub token shows as a Connected state row with Replace and Remove; the field appears only to replace it

    v1.0.0, Nov 11, 2026

  • Fix

    Plugin screens in the Field Guide layout: a Harbor intro with a line drawing on every idle, connect and result screen, a Source card, Settings as cards with a link to create a token, Deep Harbor tab indicator

    v1.0.0, Nov 11, 2026

All release notes

Updated Nov 11, 2026
View source

Generated from 4 files