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.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-
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.
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 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
-
Is a
DOMString
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.ariaBusy
-
Is a
DOMString
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
-
Is a
DOMString
reflecting thearia-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 thearia-colcount
attribute, which defines the number of columns in a table, grid, or treegrid. ElementInternals.ariaColIndex
-
Is a
DOMString
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
-
Is a
DOMString
reflecting thearia-colindextext
attribute, which defines a human readable text alternative of aria-colindex. ElementInternals.ariaColSpan
-
Is a
DOMString
reflecting thearia-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 thearia-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 thearia-description
attribute, which defines a string value that describes or annotates the current ElementInternals. ElementInternals.ariaDisabled
-
Is a
DOMString
reflecting thearia-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 thearia-expanded
attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. ElementInternals.ariaHasPopup
-
Is a
DOMString
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. -
Is a
DOMString
reflecting thearia-hidden
attribute, which indicates whether the element is exposed to an accessibility API. ElementInternals.ariaKeyShortcuts
-
Is a
DOMString
reflecting thearia-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 thearia-label
attribute, which defines a string value that labels the current ElementInternals. ElementInternals.ariaLevel
-
Is a
DOMString
reflecting thearia-level
attribute, which defines the hierarchical level of an element within a structure. ElementInternals.ariaLive
-
Is a
DOMString
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
-
Is a
DOMString
reflecting thearia-modal
attribute, which indicates whether an element is modal when displayed. ElementInternals.ariaMultiline
-
Is a
DOMString
reflecting thearia-multiline
attribute, which indicates whether a text box accepts multiple lines of input or only a single line. ElementInternals.ariaMultiSelectable
-
Is a
DOMString
reflecting thearia-multiselectable
attribute, which indicates that the user may select more than one item from the current selectable descendants. ElementInternals.ariaOrientation
-
Is a
DOMString
reflecting thearia-orientation
attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. ElementInternals.ariaPlaceholder
-
Is a
DOMString
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
-
Is a
DOMString
reflecting thearia-posinset
attribute, which defines an element's number or position in the current set of listitems or treeitems. ElementInternals.ariaPressed
-
Is a
DOMString
reflecting thearia-pressed
attribute, which indicates the current "pressed" state of toggle buttons. ElementInternals.ariaReadOnly
-
Is a
DOMString
reflecting thearia-readonly
attribute, which indicates that the element is not editable, but is otherwise operable. ElementInternals.ariaRelevant
-
Is a
DOMString
reflecting thearia-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
-
Is a
DOMString
reflecting thearia-required
attribute, which indicates that user input is required on the element before a form may be submitted. ElementInternals.ariaRoleDescription
-
Is a
DOMString
reflecting thearia-roledescription
attribute, which defines a human-readable, author-localized description for the role of an Element. ElementInternals.ariaRowCount
-
Is a
DOMString
reflecting thearia-rowcount
attribute, which defines the total number of rows in a table, grid, or treegrid. ElementInternals.ariaRowIndex
-
Is a
DOMString
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
-
Is a
DOMString
reflecting thearia-rowindextext
attribute, which defines a human readable text alternative of aria-rowindex. ElementInternals.ariaRowSpan
-
Is a
DOMString
reflecting thearia-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 thearia-selected
attribute, which indicates the current "selected" state of elements that have a selected state. ElementInternals.ariaSetSize
-
Is a
DOMString
reflecting thearia-setsize
attribute, which defines the number of items in the current set of listitems or treeitems. ElementInternals.ariaSort
-
Is a
DOMString
reflecting thearia-sort
attribute, which indicates if items in a table or grid are sorted in ascending or descending order. ElementInternals.ariaValueMax
-
Is a
DOMString
reflecting thearia-valueMax
attribute, which defines the maximum allowed value for a range widget. ElementInternals.ariaValueMin
-
Is a
DOMString
reflecting thearia-valueMin
attribute, which defines the minimum allowed value for a range widget. ElementInternals.ariaValueNow
-
Is a
DOMString
reflecting thearia-valueNow
attribute, which defines the current value for a range widget. ElementInternals.ariaValueText
-
Is a
DOMString
reflecting thearia-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.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