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

`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.ariaColIndexText` 
Experimental

A string reflecting the `aria-colindextext` attribute, which defines a human readable text alternative of aria-colindex.

`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.ariaRowIndexText` 
Experimental

A string reflecting the `aria-rowindextext` attribute, which defines a human readable text alternative of aria-rowindex.

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

| Specification |
| --- |
| HTML Standard # the-elementinternals-interface |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* More capable form controls
* Creating custom form controls with ElementInternals
* ElementInternals polyfill