Form Field

Preview

<FormField label="Email" helpText="We will never share your email.">
  <input type="email" aria-label="Email" placeholder="you@example.com" />
</FormField>

States

Mark a field required, surface an errorText in place of help text, or disabled the whole field.

The control is yours to style — this wrapper only owns the label, help and error text. The plain <input> below is demo markup: its border comes from a class in this page's own stylesheet, not from the design system. What the wrapper does give a slotted control is the focus ring — an errorText re-points --focus-ring-color to the error red, and because custom properties inherit, that reaches a native control and an esa-* component in a shadow root alike. Tab into Permit ID to see it. For a real form, reach for Text Field instead: it owns its label, help text, error text and border states, so you are not hand-rolling three of the four.

<FormField label="Project name" required>
  <input type="text" aria-label="Project name" />
</FormField>

<FormField label="Permit ID" errorText="Permit ID is required." required>
  <input type="text" aria-label="Permit ID" aria-invalid="true" />
</FormField>

<FormField label="Locked field" helpText="This field cannot be edited." disabled>
  <input type="text" aria-label="Locked field" disabled value="Read only" />
</FormField>

Sizes

The size prop scales the label; size the control yourself to match.

<FormField label="Extra small label" size="xs"> … </FormField>
<FormField label="Small label" size="sm"> … </FormField>
<FormField label="Medium label" size="md"> … </FormField>
<FormField label="Large label" size="lg"> … </FormField>

API

The control goes in the default slot — the wrapper makes no assumptions about it.

Accessibility

• The wrapper is presentational only. Its <label> has no for and does not wrap the slot, so it names nothing on its own — associate it yourself with a for/id pair.
• That is only possible for a native control. The esa-* Lit controls render into shadow DOM, and a light-DOM for can never reach an input inside a shadow root. Around one of those, treat this label as a visual caption and set the control's own label attribute instead — that one is associated.
• helpText and errorText render without an id, so they cannot be referenced by aria-describedby either, and errorText is not in a live region. Prefer the control's own help-text / error-text where it has them.
• The required asterisk is aria-hidden, because it is decoration: it used to carry aria-label="required", which does nothing at all — aria-label is ignored on a bare <span> (role=generic). The requirement itself must be set on the control, as aria-required or the native required attribute. Every esa-* form control now does both when given required.
• Set aria-invalid="true" on the slotted control whenever errorText is shown.
• disabled is opacity + pointer-events: none — it blocks the mouse only. The slotted control stays keyboard-focusable, operable, and still submits, so you must also disable it natively.
• The wrapper adds no grouping semantics. Around a set of radios or checkboxes it renders a bare <div>; the group needs its own name (see the forms contract in the accessibility skill).

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.