ElementInternals

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.

Constructor

This interface has no constructor. An ElementInternals object is returned when calling HTMLElement.attachInternals().

Properties

ElementInternals.shadowRootRead only

Returns the ShadowRoot object associated with this element.

ElementInternals.formRead only

Returns the HTMLFormElement associated with this element.

ElementInternals.statesRead only

Returns the CustomStateSet associated with this element.

ElementInternals.willValidateRead only

A boolean value which returns true if the element is a submittable element that is a candidate for constraint validation.

ElementInternals.validityRead only

Returns a ValidityState object which represents the different validity states the element can be in, with respect to constraint validation.

ElementInternals.validationMessageRead only

A string containing the validation message of this element.

ElementInternals.labelsRead only

Returns a NodeList of all of the label elements associated with this element.

Properties included from ARIA

The ElementInternals interface includes the following properties, defined on the ARIAMixin mixin.

Note: These are included in order that default accessibility semantics can be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

ElementInternals.ariaAtomic

Is a DOMString reflecting the aria-atomic attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute.

ElementInternals.ariaAutoComplete

Is a DOMString reflecting the aria-autocomplete attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made.

ElementInternals.ariaBusy

Is a DOMString reflecting the aria-busy attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user.

ElementInternals.ariaChecked

Is a DOMString reflecting the aria-checked attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state.

ElementInternals.ariaColCount

Is a DOMString reflecting the aria-colcount attribute, which defines the number of columns in a table, grid, or treegrid.

ElementInternals.ariaColIndex

Is a DOMString reflecting the aria-colindex attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid.

ElementInternals.ariaColIndexText

Is a DOMString reflecting the aria-colindextext attribute, which defines a human readable text alternative of aria-colindex.

ElementInternals.ariaColSpan

Is a DOMString reflecting the aria-colspan attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.

ElementInternals.ariaCurrent

Is a DOMString reflecting the aria-current attribute, which indicates the element that represents the current item within a container or set of related elements.

ElementInternals.ariaDescription

Is a DOMString reflecting the aria-description attribute, which defines a string value that describes or annotates the current ElementInternals.

ElementInternals.ariaDisabled

Is a DOMString reflecting the aria-disabled attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

ElementInternals.ariaExpanded

Is a DOMString reflecting the aria-expanded attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed.

ElementInternals.ariaHasPopup

Is a DOMString reflecting the aria-haspopup attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an ElementInternals.

ElementInternals.ariaHidden

Is a DOMString reflecting the aria-hidden attribute, which indicates whether the element is exposed to an accessibility API.

ElementInternals.ariaKeyShortcuts

Is a DOMString reflecting the aria-keyshortcuts attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an ElementInternals.

ElementInternals.ariaLabel

Is a DOMString reflecting the aria-label attribute, which defines a string value that labels the current ElementInternals.

ElementInternals.ariaLevel

Is a DOMString reflecting the aria-level attribute, which defines the hierarchical level of an element within a structure.

ElementInternals.ariaLive

Is a DOMString reflecting the aria-live attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

ElementInternals.ariaModal

Is a DOMString reflecting the aria-modal attribute, which indicates whether an element is modal when displayed.

ElementInternals.ariaMultiline

Is a DOMString reflecting the aria-multiline attribute, which indicates whether a text box accepts multiple lines of input or only a single line.

ElementInternals.ariaMultiSelectable

Is a DOMString reflecting the aria-multiselectable attribute, which indicates that the user may select more than one item from the current selectable descendants.

ElementInternals.ariaOrientation

Is a DOMString reflecting the aria-orientation attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.

ElementInternals.ariaPlaceholder

Is a DOMString reflecting the aria-placeholder attribute, which defines a short hint intended to aid the user with data entry when the control has no value.

ElementInternals.ariaPosInSet

Is a DOMString reflecting the aria-posinset attribute, which defines an element's number or position in the current set of listitems or treeitems.

ElementInternals.ariaPressed

Is a DOMString reflecting the aria-pressed attribute, which indicates the current "pressed" state of toggle buttons.

ElementInternals.ariaReadOnly

Is a DOMString reflecting the aria-readonly attribute, which indicates that the element is not editable, but is otherwise operable.

ElementInternals.ariaRelevant

Is a DOMString reflecting the aria-relevant attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an aria-live region are relevant and should be announced.

ElementInternals.ariaRequired

Is a DOMString reflecting the aria-required attribute, which indicates that user input is required on the element before a form may be submitted.

ElementInternals.ariaRoleDescription

Is a DOMString reflecting the aria-roledescription attribute, which defines a human-readable, author-localized description for the role of an Element.

ElementInternals.ariaRowCount

Is a DOMString reflecting the aria-rowcount attribute, which defines the total number of rows in a table, grid, or treegrid.

ElementInternals.ariaRowIndex

Is a DOMString reflecting the aria-rowindex attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid.

ElementInternals.ariaRowIndexText

Is a DOMString reflecting the aria-rowindextext attribute, which defines a human readable text alternative of aria-rowindex.

ElementInternals.ariaRowSpan

Is a DOMString reflecting the aria-rowspan attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.

ElementInternals.ariaSelected

Is a DOMString reflecting the aria-selected attribute, which indicates the current "selected" state of elements that have a selected state.

ElementInternals.ariaSetSize

Is a DOMString reflecting the aria-setsize attribute, which defines the number of items in the current set of listitems or treeitems.

ElementInternals.ariaSort

Is a DOMString reflecting the aria-sort attribute, which indicates if items in a table or grid are sorted in ascending or descending order.

ElementInternals.ariaValueMax

Is a DOMString reflecting the aria-valueMax attribute, which defines the maximum allowed value for a range widget.

ElementInternals.ariaValueMin

Is a DOMString reflecting the aria-valueMin attribute, which defines the minimum allowed value for a range widget.

ElementInternals.ariaValueNow

Is a DOMString reflecting the aria-valueNow attribute, which defines the current value for a range widget.

ElementInternals.ariaValueText

Is a DOMString reflecting the aria-valuetext attribute, which defines the human readable text alternative of aria-valuenow for a range widget.

Methods

ElementInternals.setFormValue()

Sets the element's submission value and state, communicating these to the user agent.

ElementInternals.setValidity()

Sets the validity of the element.

ElementInternals.checkValidity()

Checks if an element meets any constraint validation rules applied to it.

ElementInternals.reportValidity()

Checks if an element meets any constraint validation rules applied to it, and also sends a validation message to the user agent.

Examples

The following example demonstrates how to create a custom form-associated element with HTMLElement.attachInternals.

class CustomCheckbox extends HTMLElement {
  static formAssociated = true;

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

  /* ... */

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

let element = document.getElementById("custom-checkbox");
console.log(element.internals_.form);

Specifications

Specification
HTML Standard (HTML)
# the-elementinternals-interface

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
ElementInternals
77
79
93
No
64
No
77
77
93
55
No
12.0
checkValidity
77
79
No
No
64
No
77
77
No
55
No
12.0
form
77
79
No
No
64
No
77
77
No
55
No
12.0
labels
77
79
No
No
64
No
77
77
No
55
No
12.0
reportValidity
77
79
No
No
64
No
77
77
No
55
No
12.0
setFormValue
77
79
No
No
64
No
77
77
No
55
No
12.0
setValidity
77
79
No
No
64
No
77
77
No
55
No
12.0
shadowRoot
77
79
93
No
64
No
77
77
93
55
No
12.0
states
90
90
No
No
76
No
90
90
No
No
No
No
validationMessage
77
79
No
No
64
No
77
77
No
55
No
12.0
validity
77
79
No
No
64
No
77
77
No
55
No
12.0
willValidate
77
79
No
No
64
No
77
77
No
55
No
12.0
ariaAtomic
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaAutoComplete
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaBusy
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaChecked
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaColCount
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaColIndex
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaColSpan
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaCurrent
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaDescription
83
83
No
No
69
No
83
83
No
59
No
13.0
ariaDisabled
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaExpanded
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaHasPopup
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaHidden
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaKeyShortcuts
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaLabel
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaLevel
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaLive
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaModal
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaMultiLine
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaMultiSelectable
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaOrientation
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaPlaceholder
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaPosInSet
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaPressed
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaReadOnly
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaRelevant
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaRequired
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaRoleDescription
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaRowCount
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaRowIndex
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaRowSpan
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaSelected
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaSetSize
84
84
No
No
70
No
84
84
No
60
No
14.0
ariaSort
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaValueMax
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaValueMin
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaValueNow
81
81
No
No
68
No
81
81
No
58
No
13.0
ariaValueText
81
81
No
No
68
No
81
81
No
58
No
13.0

Polyfills

See also

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals