If your custom element is missing from FormData, being inside a <form> is not enough. Opt it into native form participation with static formAssociated = true, attach ElementInternals once, give the element a name, and update its submission value with setFormValue().
Why a custom element is missing from FormData
An autonomous custom element is not automatically a successful form control. Its visible UI and internal JavaScript state do not become form data unless the component explicitly joins the browser’s form-control model and supplies a value. The WHATWG HTML Standard defines this through form-associated custom elements and the ElementInternals API.
As an Amazon Associate I earn from qualifying purchases.
The minimum wiring looks like this:
class XRating extends HTMLElement {
static formAssociated = true;
#internals;
#value = "";
constructor() {
super();
this.#internals = this.attachInternals();
}
set value(value) {
this.#value = String(value);
this.#internals.setFormValue(this.#value);
}
get value() {
return this.#value;
}
}
customElements.define("x-rating", XRating);<form id="profile">
<x-rating name="rating"></x-rating>
</form>This example demonstrates the submission connection, not a complete user-interface component. Your component still needs to initialize and update its value from its own UI, and may need to implement disabled behavior, reset handling, or validation.
Wire the component to form submission
Opt in before registering the element
Declare static formAssociated = true on the custom-element class before calling customElements.define(). This marks the autonomous element as form-associated and enables the form-control APIs described in the standard.
#1 Best Overall
Attach internals once
Call this.attachInternals() in the constructor and retain the returned object. It provides the element’s form-related methods and properties. Calling it again on the same element raises NotSupportedError, so do not attach a second instance during later updates. See MDN’s attachInternals() reference.
Give the element a name and set its current value
Add a name attribute to the element in the form, then call this.#internals.setFormValue(value) whenever the component’s current submission value changes. The name supplies the key; setFormValue() supplies the value. Supported values include a string, a File, or a FormData object. Passing null means the element does not contribute to submission.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Keep the component’s state and its submitted value synchronized. A rating widget, for example, should call setFormValue() when a user changes the rating, not only when the element is first constructed. The optional second argument, setFormValue(value, state), lets a component preserve restoration state separately from the value submitted with the form.
Recommended Free Tools
Check the form owner and inspect FormData
A form-associated custom element can be associated with a form through containment or by using the element’s form attribute. Its ElementInternals.form property exposes its form owner. The standard’s form-associated custom-element rules define this ownership behavior.
Rank #3
To inspect the form’s current data while debugging, construct FormData from the form and examine its entries or the value for the expected name:
const form = document.querySelector("#profile");
const data = new FormData(form);
console.log([...data.entries()]);
console.log(data.getAll("rating"));The FormData() constructor reference explains how constructing the object from a form populates it from associated controls and their names and values. If the expected entry is absent, check the opt-in declaration, that internals are attached, the element’s name, whether a current value has been set, and whether the element belongs to that form.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Decide which native control behaviors your component needs
Form association includes more than collecting a value. The component should implement the related behaviors its design requires; opting in does not automatically create a complete, accessible control UI.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute- Disabled state: A disabled form-associated custom element is non-interactive and its value is not submitted. Ensure the component’s UI reflects that state.
- Constraint validation: Use
setValidity()to report validity as needed. An empty flags object indicates that the element satisfies its constraints;checkValidity()andreportValidity()can be used where appropriate. - Reset and restored state: Define how the component’s UI responds when its form resets and when the browser restores state. Keep the displayed value aligned with the value the component reports for submission.
- Labels and ownership: Support labels and form ownership in the way the component’s design requires. Form association provides related APIs, but the component remains responsible for integrating them into its UI.
When a manual submit handler may be enough
If a component only needs to contribute a value at submission time, application code can collect its state in a form submit handler and add it to a FormData object. That approach requires your application to maintain the synchronization and submission logic itself. Use native form association when the component should participate as a control in the browser’s form model, including behaviors such as ownership, disabled handling, labels, reset, or constraint validation.
Check browser support for your target
MDN labels attachInternals() Baseline and widely available, with cross-browser availability since March 2023. That general status does not establish support for every method or behavior in every browser and version your application targets; verify the APIs and behavior your component depends on against your browser support requirements.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
