Skip to content

x-form.md

Latest commit

 

History

History
195 lines (139 loc) · 5.89 KB

x-form.md

File metadata and controls

195 lines (139 loc) · 5.89 KB

x-form

A native Web Component that wraps a <form> element to handle submission, validation gating, loading state, and server-side error injection. Consumers slot in their own x-form-field, x-checkbox, and submit buttons.

Tag name

<x-form></x-form>

Observed attributes

Attribute Type Default Description
loading boolean false Prevents submit dispatch and sets aria-busy="true" on the shadow form
novalidate boolean false Skips constraint validation before dispatching the submit event
autocomplete string "on" Forwarded directly to the shadow <form> element ("on" | "off")

Boolean attributes follow standard HTML conventions: presence means true, absence means false.

Properties

Property Type Reflects attribute
loading boolean loading
novalidate boolean novalidate
autocomplete string autocomplete

Methods

Method Signature Description
submit() () → void Programmatically submits the form via requestSubmit() — triggers the full validation + event pipeline
reset() () → void Calls form.reset() on the shadow form — triggers formResetCallback on associated form-associated elements
setFieldError(name, msg) (string, string|null) → void Sets the error attribute on the first light-DOM element matching [name="…"]. Pass "" or null to clear.
clearErrors() () → void Removes the error attribute from all light-DOM elements that currently have it

Events

Event Cancelable Detail When
x-form-submit yes {values: Object} After validation passes (or novalidate), and not while loading is set
x-form-reset no {} After the shadow form.reset() completes

x-form-submit detail

values is a plain JS object keyed by field name. Collection strategy:

  • Queries this.querySelectorAll("[name]:not([disabled])") in the light DOM.
  • Checkbox/radio elements (detected by type="checkbox", type="radio", or tagName === "x-checkbox") are only included when checked === true.
  • All other fields contribute field.value || "".

Slots

Slot Description
(default) Form fields, submit buttons, and any other content

x-form imposes no layout on slotted content. Use the --x-form-gap and --x-form-width CSS custom properties to control the flex column layout of the shadow <form>.

CSS custom properties

Property Default Description
--x-form-gap 1rem gap between flex items in the shadow [part=root]
--x-form-width 100% Width of the shadow <form>

Parts

Part Element
root The shadow <form> element

Use ::part(root) to style the inner form container directly.

Shadow DOM structure

<form part="root" novalidate autocomplete="on">
  <slot></slot>
</form>

The shadow <form> always has the novalidate HTML attribute so the browser does not show native constraint UI automatically. Validation is run manually via form.reportValidity() during the submit lifecycle, which still surfaces browser/ElementInternals validation UI on invalid fields.

Submit lifecycle

  1. User clicks a type="submit" button inside the slot, or el.submit() is called.
  2. requestSubmit() fires the native submit event on the shadow form.
  3. The handler always calls event.preventDefault().
  4. If loading is set → bail silently (no event dispatched).
  5. If novalidate is not set → call form.reportValidity():
    • Returns false → bail (browser/ElementInternals surfaces validation UI).
    • Returns true → continue.
  6. Collect values from light DOM.
  7. Dispatch cancelable x-form-submit with {values}.
  8. Consumer handles submission, sets loading, then clears it and optionally calls setFieldError.

Accessibility

  • aria-busy="true" is set on the shadow <form> while loading is active.
  • Field-level errors are communicated via the error attribute on x-form-field (which sets aria-invalid and shows an ARIA live region).
  • novalidate on the host skips constraint validation but does not suppress field-level error attributes set by the consumer.

Usage examples

Basic login form

<x-form id="my-form">
  <x-form-field label="Email"    name="email"    type="email"    required></x-form-field>
  <x-form-field label="Password" name="password" type="password" required></x-form-field>
  <button type="submit">Sign in</button>
</x-form>

<script>
  document.getElementById('my-form').addEventListener('x-form-submit', e => {
    console.log(e.detail.values); // { email: '...', password: '...' }
  });
</script>

Async submit with loading state

form.addEventListener('x-form-submit', async e => {
  e.preventDefault();
  form.setAttribute('loading', '');
  try {
    await api.login(e.detail.values);
  } catch (err) {
    form.setFieldError('email', err.message);
  } finally {
    form.removeAttribute('loading');
  }
});

Server-side error injection

// After receiving a 422 response:
form.setFieldError('email', 'An account with this email already exists.');
form.setFieldError('password', 'Password does not meet requirements.');

// Clear all errors (e.g. on reset):
form.clearErrors();

Disable browser autocomplete

<x-form autocomplete="off">
  <!-- fields -->
</x-form>

Skip HTML5 validation

<x-form novalidate>
  <!-- fields — submitted even if required fields are empty -->
</x-form>

Custom layout spacing

x-form {
  --x-form-gap: 1.5rem;
  --x-form-width: 400px;
}