Widely available Valuable for component libraries that need custom controls without giving up standard form integration.

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 ComponentsFormsCustom elements

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

HTML 
class MyInput extends HTMLElement {
  static formAssociated = true;
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
  }

  set value(v) {
    this.#internals.setFormValue(v);
  }

  get validity() {
    return this.#internals.validity;
  }
}
customElements.define('my-input', MyInput);

Live demo

Form value bridge

Use ElementInternals to submit a value from a custom element with the surrounding form.

PreviewFullscreen

Required state card

Show how a form-associated element can participate in normal form flow.

PreviewFullscreen

Support fallback note

Explain the current support state when ElementInternals is missing.

PreviewFullscreen

Use cases

  • Design-system controls

    Build custom date pickers, segmented controls, or token inputs that still submit with a plain HTML form.

  • Native form workflows

    Keep browser validation and submission behavior while wrapping the UI in reusable custom elements.

Cautions

  • Custom form controls still need predictable value handling, validation messages, and state synchronization.
  • Do not assume native accessibility behavior appears automatically; test the composed control thoroughly.

Accessibility

  • Expose labels, value state, and validation errors the same way a native form control would.
  • Keyboard interaction should match the expectation users already have for controls with similar roles.

Related links