files/en-us/web/api/elementinternals/index.md
{{APIRef("Web Components")}}
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.
This interface has no constructor. An ElementInternals object is returned when calling {{domxref("HTMLElement.attachInternals()")}}.
The ElementInternals 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 the Accessibility Object Model explainer.
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.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.aria-braillelabel attribute, which defines the braille label of the element.aria-brailleroledescription attribute, which defines the ARIA braille role description of the element.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.aria-checked attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state.aria-colcount attribute, which defines the number of columns in a table, grid, or treegrid.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.aria-colindextext attribute, which defines a human readable text alternative of aria-colindex.aria-colspan attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.aria-current attribute, which indicates the element that represents the current item within a container or set of related elements.aria-description attribute, which defines a string value that describes or annotates the current ElementInternals.aria-disabled attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.aria-expanded attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed.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.aria-hidden attribute, which indicates whether the element is exposed to an accessibility API.aria-invalid attribute, which indicates the entered value does not conform to the format expected by the application.aria-keyshortcuts attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an object.aria-label attribute, which defines a string value that labels the current object.aria-level attribute, which defines the hierarchical level of an element within a structure.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.aria-modal attribute, which indicates whether an element is modal when displayed.aria-multiline attribute, which indicates whether a text box accepts multiple lines of input or only a single line.aria-multiselectable attribute, which indicates that the user may select more than one item from the current selectable descendants.aria-orientation attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.aria-placeholder attribute, which defines a short hint intended to aid the user with data entry when the control has no value.aria-posinset attribute, which defines an element's number or position in the current set of listitems or treeitems.aria-pressed attribute, which indicates the current "pressed" state of toggle buttons.aria-readonly attribute, which indicates that the element is not editable, but is otherwise operable.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.aria-required attribute, which indicates that user input is required on the element before a form may be submitted.aria-roledescription attribute, which defines a human-readable, author-localized description for the role of an Element.aria-rowcount attribute, which defines the total number of rows in a table, grid, or treegrid.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.aria-rowindextext attribute, which defines a human readable text alternative of aria-rowindex.aria-rowspan attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.aria-selected attribute, which indicates the current "selected" state of elements that have a selected state.aria-setsize attribute, which defines the number of items in the current set of listitems or treeitems.aria-sort attribute, which indicates if items in a table or grid are sorted in ascending or descending order.aria-valueMax attribute, which defines the maximum allowed value for a range widget.aria-valueMin attribute, which defines the minimum allowed value for a range widget.aria-valueNow attribute, which defines the current value for a range widget.aria-valuetext attribute, which defines the human-readable text alternative of aria-valuenow for a range widget.The properties reflect the elements specified by id reference in the corresponding attributes, but with some caveats. See Reflected element references in the Reflected attributes guide for more information.
composite widget, combobox, textbox, group, or application.
Reflects the aria-activedescendant attribute.aria-controls attribute.aria-describedby attribute.aria-details attribute.aria-errormessage attribute.aria-flowto attribute.aria-labelledby attribute.aria-owns attribute.The following example demonstrates how to create a custom form-associated element with {{domxref("HTMLElement.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 it
form.appendChild(element);
console.log(element.internals_.form);
// expected output: <form><custom-checkbox></custom-checkbox></form>
{{Specifications}}
{{Compat}}