Form-Associated Custom Elements: Web Components That Belong in a Form

Custom elements have been available for years, but they struggle when placed inside a form. The value is not captured in FormData, required attribute has no effect, hitting reset leaves the control with stale state, and the browser's validation mechanism fails to point at it. This led to the common workaround of rendering a hidden input inside the component and manually keeping it in sync.

However, form-associated custom elements have arrived, available in Baseline in Chromium, Firefox, and Safari 16.4 and above. These elements allow a custom component to participate in a form as a first-class control instead of just being a decoration next to one.

To make an element a form control, two lines of code are required: setting a static property `formAssociated` to `true` and calling the `attachInternals()` method. The `RatingInput` class demonstrates this, extending `HTMLElement` and setting `formAssociated` to `true`. Inside `attachInternals()`, an `ElementInternals` object is returned, which serves as the private communication channel between the component and the form.

This object can be used to pass a string, a File, or a FormData object when a control needs to contribute multiple named values.

Form-associated custom elements also provide free lifecycle callbacks. The `formResetCallback` runs when the form is reset using the `form.reset()` method, allowing the custom control to reset its value. The `formDisabledCallback` is triggered when the element or its enclosing `fieldset` is disabled, and the `formStateRestoreCallback` restores the component's state on back-navigation and session restore.

Finally, validation is handled by the browser understanding the `setValidity()` method. The first argument is a `ValidityStateFlags` dictionary using the same flag names as native inputs, enabling custom controls to participate in validation and providing a more accurate experience for users.