Widely available Supported across all major browsers. Safe to use in production.

Form-associated custom elements

The ElementInternals interface of the Document Object Model gives web developers a way to allow custom elements to fully participate in HTML forms. It provides utilities for working with these elements in the same way you would work with any standard HTML form element, and also exposes the Accessibility Object Model to the element.

Web Components

Browser support

Feature Desktop Mobile
Chrome
Edge
Firefox
Safari
Chrome Android
Safari iOS
ElementInternals
77
79
93
16.4
77
16.4
checkValidity

The checkValidity() method of the ElementInternals interface checks if the element meets any constraint validation rules applied to it.
77
79
98
16.4
77
16.4
form

The form read-only property of the ElementInternals interface returns the HTMLFormElement associated with this element.
77
79
98
16.4
77
16.4
labels

The labels read-only property of the ElementInternals interface returns the labels associated with the element.
77
79
98
16.4
77
16.4
reportValidity

The reportValidity() method of the ElementInternals interface checks if the element meets any constraint validation rules applied to it.
77
79
98
16.4
77
16.4
setFormValue

The setFormValue() method of the ElementInternals interface sets the element's submission value and state, communicating these to the user agent.
77
79
98
16.4
77
16.4
setValidity

The setValidity() method of the ElementInternals interface sets the validity of the element.
77
79
98
16.4
77
16.4
validationMessage

The validationMessage read-only property of the ElementInternals interface returns the validation message for the element.
77
79
98
16.4
77
16.4
validity

The validity read-only property of the ElementInternals interface returns a ValidityState object which represents the different validity states the element can be in, with respect to constraint validation.
77
79
98
16.4
77
16.4
willValidate

The willValidate read-only property of the ElementInternals interface returns true if the element is a submittable element that is a candidate for constraint validation.
77
79
98
16.4
77
16.4
attachInternals

The HTMLElement.attachInternals() method returns an ElementInternals object. This method allows a custom element to participate in HTML forms. The ElementInternals interface provides utilities for working with these elements in the same way you would work with any standard HTML form element, and also exposes the Accessibility Object Model to the element.
77
79
93
16.4
77
16.4
1+Supported (version) Not supported ※Has note Sub-feature descriptions sourced from MDN Web Docs (CC BY-SA 2.5)

Syntax

JAVASCRIPT 
class CustomCheckbox extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals_ = this.attachInternals();
  }

  // …
}

window.customElements.define("custom-checkbox", CustomCheckbox);

let element = document.createElement("custom-checkbox");
let form = document.createElement("form");

// Append element to form to associate it
form.appendChild(element);

console.log(element.internals_.form);
// expected output: <form><custom-checkbox></custom-checkbox></form>

Use cases

  • Using Form-associated custom elements

    The ElementInternals interface of the Document Object Model gives web developers a way to allow custom elements to fully participate in HTML forms.

Cautions

  • May not be supported in older browsers.

Implementation notes

  • Some APIs require a secure context (HTTPS) or user activation. Check the requirements before use.

Related links