W3cubDocs

/Web APIs

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().

Instance properties

ElementInternals.shadowRoot Read only

Returns the ShadowRoot object associated with this element.

ElementInternals.form Read only

Returns the HTMLFormElement associated with this element.

ElementInternals.states Read only Experimental

Returns the CustomStateSet associated with this element.

ElementInternals.willValidate Read only

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

ElementInternals.validity Read only

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

ElementInternals.validationMessage Read only

A string containing the validation message of this element.

ElementInternals.labels Read only

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

Instance 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

A string 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

A string 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

A string 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

A string 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

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

ElementInternals.ariaColIndex

A string 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.ariaColSpan

A string 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

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

ElementInternals.ariaDescription

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

ElementInternals.ariaDisabled

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

ElementInternals.ariaExpanded

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

ElementInternals.ariaHasPopup

A string 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

A string reflecting the aria-hidden attribute, which indicates whether the element is exposed to an accessibility API.

ElementInternals.ariaKeyShortcuts

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

ElementInternals.ariaLabel

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

ElementInternals.ariaLevel

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

ElementInternals.ariaLive

A string 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

A string reflecting the aria-modal attribute, which indicates whether an element is modal when displayed.

ElementInternals.ariaMultiline

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

ElementInternals.ariaMultiSelectable

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

ElementInternals.ariaOrientation

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

ElementInternals.ariaPlaceholder

A string 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

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

ElementInternals.ariaPressed

A string reflecting the aria-pressed attribute, which indicates the current "pressed" state of toggle buttons.

ElementInternals.ariaReadOnly

A string reflecting the aria-readonly attribute, which indicates that the element is not editable, but is otherwise operable.

ElementInternals.ariaRelevant Non-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 an aria-live region are relevant and should be announced.

ElementInternals.ariaRequired

A string reflecting the aria-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 the ARIA techniques page.

ElementInternals.ariaRoleDescription

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

ElementInternals.ariaRowCount

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

ElementInternals.ariaRowIndex

A string 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.ariaRowSpan

A string 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

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

ElementInternals.ariaSetSize

A string reflecting the aria-setsize attribute, which defines the number of items in the current set of listitems or treeitems.

ElementInternals.ariaSort

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

ElementInternals.ariaValueMax

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

ElementInternals.ariaValueMin

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

ElementInternals.ariaValueNow

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

ElementInternals.ariaValueText

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

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 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.

js

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

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 16.4 77 77 93 55 16.4 12.0
ariaActiveDescendantElement No No No No No 16.4 No No No No 16.4 No
ariaAtomic 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaAutoComplete 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaBusy 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaChecked 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaColCount 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaColIndex 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaColSpan 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaControlsElements No No No No No 16.4 No No No No 16.4 No
ariaCurrent 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaDescribedByElements No No No No No 16.4 No No No No 16.4 No
ariaDescription 83 83 119 No 69 No 83 83 119 59 No 13.0
ariaDetailsElements No No No No No 16.4 No No No No 16.4 No
ariaDisabled 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaErrorMessageElements No No No No No 16.4 No No No No 16.4 No
ariaExpanded 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaFlowToElements No No No No No 16.4 No No No No 16.4 No
ariaHasPopup 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaHidden 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaInvalid 102 102 119 No 88 16.4 102 102 119 70 16.4 19.0
ariaKeyShortcuts 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaLabel 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaLabelledByElements No No No No No 16.4 No No No No 16.4 No
ariaLevel 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaLive 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaModal 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaMultiLine 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaMultiSelectable 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaOrientation 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaOwnsElements No No No No No 16.4 No No No No 16.4 No
ariaPlaceholder 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaPosInSet 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaPressed 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaReadOnly 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaRelevant 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaRequired 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaRoleDescription 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaRowCount 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaRowIndex 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaRowSpan 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaSelected 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaSetSize 84 84 119 No 70 16.4 84 84 119 60 16.4 14.0
ariaSort 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaValueMax 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaValueMin 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaValueNow 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
ariaValueText 81 81 119 No 68 16.4 81 81 119 58 16.4 13.0
checkValidity 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
form 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
labels 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
reportValidity 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
role 103 103 119 No 89 16.4 103 103 119 71 16.4 20.0
setFormValue 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
setValidity 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
shadowRoot 88 88 93 No 74 16.4 88 88 93 63 16.4 15.0
states 90 90 No No 76 No 90 90 No 64 No 15.0
validationMessage 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
validity 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0
willValidate 77 79 98 No 64 16.4 77 77 98 55 16.4 12.0

See also

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