Skip to content

Field validation enhancement

Preview Available in release assets

Progressively mirror a native constraint-validation failure as an inline description without replacing browser validation or form submission.

Field validation enhancement primary example

Show code
<div class="thin-field" data-enhance="field-validation" data-invalid-message="Enter a valid email address.">
  <label for="enhanced-email">Email address</label>
  <input id="enhanced-email" name="email" type="email" autocomplete="email" required aria-describedby="enhanced-email-hint">
  <small class="thin-hint" id="enhanced-email-hint">Used only for order updates.</small>
</div>
<script type="module">
  import { observeNativeBehaviors } from "/behaviors.js";
  observeNativeBehaviors();
</script>

Each authored example uses the production assets and includes copyable markup.

Generated inline explanation

An optional message is revealed only after the native invalid event.

Show code
<div class="thin-field" data-enhance="field-validation" data-invalid-message="Enter a valid email address.">
  <label for="enhanced-email">Email address</label>
  <input id="enhanced-email" name="email" type="email" autocomplete="email" required aria-describedby="enhanced-email-hint">
  <small class="thin-hint" id="enhanced-email-hint">Used only for order updates.</small>
</div>
<script type="module">
  import { observeNativeBehaviors } from "/behaviors.js";
  observeNativeBehaviors();
</script>

Authored inline error region

Applications may author the error node and let the behavior manage its visibility and description relationship.

Show code
<div class="thin-field" data-enhance="field-validation">
  <label for="enhanced-postcode">Postal code</label>
  <input id="enhanced-postcode" name="postcode" required pattern="[0-9]{5}" aria-describedby="enhanced-postcode-hint">
  <small class="thin-hint" id="enhanced-postcode-hint">Five digits.</small>
  <small class="thin-error" id="enhanced-postcode-error" data-field-error hidden>Enter a five-digit postal code.</small>
</div>
<script type="module">
  import { observeNativeBehaviors } from "/behaviors.js";
  observeNativeBehaviors();
</script>

Anatomy

  • Canonical Field presentation on a .thin-field host with data-enhance=field-validation
  • Explicit label and native form control
  • Optional persistent hint
  • Generated or authored inline validation description

Variants and sizes

  • Generated inline explanation — shown above
  • Authored inline error region — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • No JavaScript
  • Native invalid event
  • Invalid after submission
  • Valid after editing
  • Authored description preserved
  • Long localized validation message
  • Reconnected host

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

The behavior listens for the native invalid event and valid input, then mirrors the current failure as descriptive text. It does not prevent submission, call reportValidity, set custom validity, suppress the browser message, or replace the control's value.

Accessibility

The enhancement adds aria-invalid and appends the inline error ID to aria-describedby without removing authored descriptions. Generated errors intentionally have no alert or live-region role, avoiding a second immediate announcement alongside browser constraint validation. Confirm the resulting description and native message with the #240 screen-reader/browser evidence before promotion beyond Preview.

Contract
NATIVE
Basis
Native constraint validation with an optional Light-DOM enhancement; no APG widget
Behavior guarantees
  • Adds an inline explanation on the native invalid event and references it with aria-describedby.
  • Never prevents submission, calls reportValidity(), replaces the browser's validation UI, or adds role=alert or aria-live.
  • Removes generated descriptions on reconnect.
Evidence
  • tests/browser/field-contract.spec.ts
  • tests/unit/behaviors/field.test.ts
  • tests/unit/library/field-contract.test.ts

API

Use data-enhance=field-validation on a .thin-field host and call observeNativeBehaviors() from /behaviors.js. Optional data-invalid-message supplies application-owned text; otherwise the browser validationMessage is mirrored. An authored error can use data-field-error, and its text is preserved.

Behavior tier: dependency-free

Hosts

Apply the class to the HTML element that supplies the appropriate landmark or content role.

  • .thin-field[data-enhance~=field-validation]

Custom properties

PropertyDefaultDescription
--thin-field-spacevar(--thin-space-xs)Gap between the field label, control, hint, and error.

Examples

Progressively enhanced email fieldThe field keeps its native behavior and gains inline validation feedback.
Used only for order updates.
<div class="thin-field" data-enhance="field-validation" data-invalid-message="Enter a valid email address.">
  <label for="enhanced-email">Email address</label>
  <input id="enhanced-email" name="email" type="email" autocomplete="email" required aria-describedby="enhanced-email-hint">
  <small class="thin-hint" id="enhanced-email-hint">Used only for order updates.</small>
</div>
<script type="module">
  import { observeNativeBehaviors } from "/behaviors.js";
  observeNativeBehaviors();
</script>

Fallback

The explicit label, native constraint validation, submitted name and value, autocomplete, and ordinary form submission work before the optional inline validation connects.

Assets and dependencies

  • /components.css
  • /behaviors.js

Dependencies: None

Source: packages/ui/src/items/field/style.ts

Composition

Derived from the examples and style specs, not authored.

Composes