ElementInternals

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨March 2023⁩.

* Some parts of this feature may have varying levels of support.

TheElementInternals interface of theDocument 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 theAccessibility Object Model to the element.

Constructor

This interface has no constructor. AnElementInternals object is returned when callingHTMLElement.attachInternals().

Instance properties

ElementInternals.shadowRootRead only: Returns theShadowRoot object associated with this element.
ElementInternals.formRead only: Returns theHTMLFormElement associated with this element.
ElementInternals.statesRead only: Returns theCustomStateSet associated with this element.
ElementInternals.willValidateRead only: A boolean value which returns true if the element is a submittable element that is a candidate forconstraint validation.
ElementInternals.validityRead only: Returns aValidityState 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 aNodeList of all of the label elements associated with this element.

Instance properties included from ARIA

TheElementInternals interface also includes the following properties.

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 theAccessibility Object Model explainer.

ElementInternals.ariaAtomic: A string reflecting thearia-atomic attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by thearia-relevant attribute.
ElementInternals.ariaAutoComplete: A string reflecting thearia-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.ariaBrailleLabel: A string reflecting thearia-braillelabel attribute, which defines the braille label of the element.
ElementInternals.ariaBrailleRoleDescription: A string reflecting thearia-brailleroledescription attribute, which defines the ARIA braille role description of the element.
ElementInternals.ariaBusy: A string reflecting thearia-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: A string reflecting thearia-checked attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state.
ElementInternals.ariaColCount: A string reflecting thearia-colcount attribute, which defines the number of columns in a table, grid, or treegrid.
ElementInternals.ariaColIndex: A string reflecting thearia-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: A string reflecting thearia-colindextext attribute, which defines a human readable text alternative of aria-colindex.
ElementInternals.ariaColSpan: A string reflecting thearia-colspan attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
ElementInternals.ariaCurrent: A string reflecting thearia-current attribute, which indicates the element that represents the current item within a container or set of related elements.
ElementInternals.ariaDescription: A string reflecting thearia-description attribute, which defines a string value that describes or annotates the current ElementInternals.
ElementInternals.ariaDisabled: A string reflecting thearia-disabled attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.
ElementInternals.ariaExpanded: A string reflecting thearia-expanded attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed.
ElementInternals.ariaHasPopup: A string reflecting thearia-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: A string reflecting thearia-hidden attribute, which indicates whether the element is exposed to an accessibility API.
ElementInternals.ariaInvalid: A string reflecting thearia-invalid attribute, which indicates the entered value does not conform to the format expected by the application.
ElementInternals.ariaKeyShortcuts: A string reflecting thearia-keyshortcuts attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an object.
ElementInternals.ariaLabel: A string reflecting thearia-label attribute, which defines a string value that labels the current object.
ElementInternals.ariaLevel: A string reflecting thearia-level attribute, which defines the hierarchical level of an element within a structure.
ElementInternals.ariaLive: A string reflecting thearia-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: A string reflecting thearia-modal attribute, which indicates whether an element is modal when displayed.
ElementInternals.ariaMultiline: A string reflecting thearia-multiline attribute, which indicates whether a text box accepts multiple lines of input or only a single line.
ElementInternals.ariaMultiSelectable: A string reflecting thearia-multiselectable attribute, which indicates that the user may select more than one item from the current selectable descendants.
ElementInternals.ariaOrientation: A string reflecting thearia-orientation attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
ElementInternals.ariaPlaceholder: A string reflecting thearia-placeholder attribute, which defines a short hint intended to aid the user with data entry when the control has no value.
ElementInternals.ariaPosInSet: A string reflecting thearia-posinset attribute, which defines an element's number or position in the current set of listitems or treeitems.
ElementInternals.ariaPressed: A string reflecting thearia-pressed attribute, which indicates the current "pressed" state of toggle buttons.
ElementInternals.ariaReadOnly: A string reflecting thearia-readonly attribute, which indicates that the element is not editable, but is otherwise operable.
ElementInternals.ariaRelevantNon-standard: A string 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 anaria-live region are relevant and should be announced.
ElementInternals.ariaRequired: A string reflecting thearia-required attribute, which indicates that user input is required on the element before a form may be submitted.
ElementInternals.role: A string which contains an ARIA role. A full list of ARIA roles can be found on theARIA techniques page.
ElementInternals.ariaRoleDescription: A string reflecting thearia-roledescription attribute, which defines a human-readable, author-localized description for the role of an Element.
ElementInternals.ariaRowCount: A string reflecting thearia-rowcount attribute, which defines the total number of rows in a table, grid, or treegrid.
ElementInternals.ariaRowIndex: A string reflecting thearia-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: A string reflecting thearia-rowindextext attribute, which defines a human readable text alternative of aria-rowindex.
ElementInternals.ariaRowSpan: A string reflecting thearia-rowspan attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.
ElementInternals.ariaSelected: A string reflecting thearia-selected attribute, which indicates the current "selected" state of elements that have a selected state.
ElementInternals.ariaSetSize: A string reflecting thearia-setsize attribute, which defines the number of items in the current set of listitems or treeitems.
ElementInternals.ariaSort: A string reflecting thearia-sort attribute, which indicates if items in a table or grid are sorted in ascending or descending order.
ElementInternals.ariaValueMax: A string reflecting thearia-valueMax attribute, which defines the maximum allowed value for a range widget.
ElementInternals.ariaValueMin: A string reflecting thearia-valueMin attribute, which defines the minimum allowed value for a range widget.
ElementInternals.ariaValueNow: A string reflecting thearia-valueNow attribute, which defines the current value for a range widget.
ElementInternals.ariaValueText: A string reflecting thearia-valuetext attribute, which defines the human-readable text alternative of aria-valuenow for a range widget.

Instance properties reflected from ARIA element references

The properties reflect the elements specified byid reference in the corresponding attributes, but with some caveats. SeeReflected element references in theReflected attributes guide for more information.

ElementInternals.ariaActiveDescendantElement: An element that represents the current active element when focus is on acomposite widget,combobox,textbox,group, orapplication.Reflects thearia-activedescendant attribute.
ElementInternals.ariaControlsElements: An array of elements whose contents or presence are controlled by the element it is applied to.Reflects thearia-controls attribute.
ElementInternals.ariaDescribedByElements: An array of elements that contain the accessible description for the element it is applied to.Reflects thearia-describedby attribute.
ElementInternals.ariaDetailsElements: An array of elements that provide accessible details for the element it is applied to.Reflects thearia-details attribute.
ElementInternals.ariaErrorMessageElements: An array of elements that provide an error message for the element it is applied to.Reflects thearia-errormessage attribute.
ElementInternals.ariaFlowToElements: An array of elements that identify the next element (or elements) in an alternate reading order of content, overriding the general default reading order at the user's discretion.Reflects thearia-flowto attribute.
ElementInternals.ariaLabelledByElements: An array of elements that provide the accessible name for the element it is applied to.Reflects thearia-labelledby attribute.
ElementInternals.ariaOwnsElements: An array of elements owned by the element this is applied to.This is used to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship.Reflects thearia-owns attribute.

Instance 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 anyconstraint validation rules applied to it.
ElementInternals.reportValidity(): Checks if an element meets anyconstraint 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 withHTMLElement.attachInternals.

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 itform.appendChild(element);console.log(element.internals_.form);// expected output: <form><custom-checkbox></custom-checkbox></form>

Specifications

Specification
HTML # the-elementinternals-interface

Browser compatibility

Help improve MDN

Learn how to contribute

This page was last modified on⁨May 2, 2025⁩ byMDN contributors.

View this page on GitHub •Report a problem with this content

Movatterモバイル変換