Custom elements have long been unable to behave like native form controls, but ElementInternals changes that. The standard shipped in Chrome 77 and is landing in other browsers, bringing form participation and an accessibility API to elements such as <my-custom-element>. The examples below use LitElement from Google's Polymer team, though the library is optional for writing custom elements.
The starting point: a control the form cannot see
Our sample is a <rad-input> that keeps its styles inside the shadow DOM and carries basic accessibility support. It sits in a form alongside a vanilla HTML input that has a default value. On submit, the handler calls preventDefault to stop the page reloading, then builds a FormData object, turns it into a JSON string and appends that to an <output> element. Only the name="basic" field shows up, because the custom element has no connection to the form.
Wiring the element into the form
The fix starts in the constructor, where you call attachInternals and keep the returned instance. For browsers without native support, the page can import an ElementInternals polyfill. The element also needs a static formAssociated getter that returns true before it can use the new APIs.
class RadInput extends LitElement {
static get formAssociated() {
return true;
}
constructor() {
super();
this.internals = this.attachInternals();
}
}
What the internals object exposes
setFormValue(value: string|FormData|File, state?: any): voidregisters the element's value with its parent form; anullvalue keeps the element out of submission entirely.formpoints at the parent form when one exists.setValidity(flags: Partial<ValidityState>, message?: string, anchor?: HTMLElement): voiddrives the control's validity state. An invalid form requires a validation message, and if the built-in validity keys are insufficient there is a catch-allcustomError.willValidatereports whether the element is evaluated at submit time.validitymirrors the semantics ofHTMLInputElement.prototype.validity.validationMessageholds the message passed tosetValiditywhen the control was marked invalid.checkValidityreturnstrueorfalse, firing aninvalidevent in the latter case.reportValiditybehaves the same but reports problems to the user when the event is not cancelled.labelslists the elements labelling this one throughlabel[for].- Additional controls set ARIA information on the element.
Registering a value
Inside _onInput, a call to this.internals.setFormValue tells the form to register the element's value under its name attribute. A firstUpdated method (roughly connectedCallback outside LitElement) sets the value to an empty string after rendering, so the element always carries a value; passing null instead would leave it out of the form. After this, submitting produces a radInput entry in the <output>, and the element appears as a radInput property on the HTMLFormElement. Submitting with no value still goes through, however, so validation has to be added explicitly.
Constraint validation
setValidity takes three arguments. The first is a partial ValidityState: setting any flag marks the control invalid, while passing an object literal ({}) resets validity to valid. The second is the validity message — required when the control is invalid and not permitted when it is valid. The third is an optional validation target that decides where focus lands if the form is submitted as invalid or reportValidity is called.
A new method on the element carries this logic: it reads the control's value and input, and if the value is an empty string while the element is marked required, it calls internals.setValidity and toggles validity. Calling that method from both firstUpdated and _onInput completes the validation behaviour.
_manageRequired() {
const { value } = this;
const input = this.shadowRoot.querySelector('input');
if (value === '' && this.required) {
this.internals.setValidity({
valueMissing: true
}, 'This field is required', input);
} else {
this.internals.setValidity({});
}
}
With this in place, submitting before entering a value shows an error message in browsers that support ElementInternals. The polyfill cannot display validation errors, since there is no reliable way to trigger the native validation popup in non-supporting browsers.
Accessibility state
The example element gains a _required property that acts as a getter and setter proxy for this.required. Forwarding required to internals.ariaRequired tells screen readers that the element expects a value. The polyfill does this by adding an aria-required attribute; in browsers with native support the attribute is not added, because the property is inherent to the element.
get required() {
return this._required;
}
set required(isRequired) {
this._required = isRequired;
this.internals.ariaRequired = isRequired;
}
Composing a reusable macro control
The most striking capability of ElementInternals is that setFormValue accepts FormData objects as well as strings and files. That makes it possible to package several controls as one reusable field — an address form, for instance, shared across multiple applications.
The example builds a form inside the element's shadow root from four <rad-input> elements. Rather than passing a string to setFormValue, it passes the entire value of that inner form, so the element hands the values of every child input up to the outer form. Constraints and added styling, behaviour or slotted content could be layered on this arrangement just as easily.



