ElementInternals: Making Custom Elements Form-Friendly

Why it exists

Before ElementInternals, custom elements were isolated islands. You could build a beautiful custom input, but getting it to work inside a <form>—to be validated, have its value submitted, or be associated with a <label>—required complex, brittle JavaScript workarounds. ElementInternals was created to solve this, providing a standard API for custom elements to become first-class citizens of HTML forms.

The mental model

Think of ElementInternals as a backstage pass for your custom element. Normally, only native elements like <input> and <select> are allowed in the "form internals" area. By calling attachInternals(), your custom element gets this pass, allowing it to talk to the parent <form>, report its validity status, set its value for submission, and even expose its state to CSS for styling.

How it works

Inside your custom element's class constructor, you call this.attachInternals(). This returns an ElementInternals object, which you store as a property (e.g., this._internals). This object has methods and properties to manage the element's role within a form. For example, you use this._internals.setValidity() to report validation errors and this._internals.setFormValue() to set the value that gets submitted. It also exposes properties for setting default ARIA attributes, like this._internals.role = 'checkbox'.

When to use it

Use ElementInternals whenever you're creating a custom element that should behave like a form control. This is a must-have for building robust, reusable components in a design system, such as custom-styled checkboxes, radio buttons, or complex input fields with unique validation logic. It's also the standard way to manage custom pseudo-class states for styling (e.g., :--loading).

When not to use it

Don't use it for presentational components that don't collect user data or have a state relevant to a form. For example, a custom <card> or <icon> component doesn't need form integration. Using ElementInternals where it's not needed adds unnecessary complexity; it is specifically for elements that need to act like form controls.

One canonical example

For a custom checkbox, you'd call this.attachInternals() in the constructor. When the user clicks it, you'd toggle its state, call this._internals.setFormValue(this.checked ? 'on' : null), and perhaps this._internals.states.toggle('--checked', this.checked). You would also set this._internals.role = 'checkbox' and this._internals.ariaChecked = this.checked.toString() to ensure it's accessible. Now it works in a form just like a native checkbox.