mdn / mdn/content

All `ElementInternals` docs for `ARIAMixin` properties are incorrect

Open
#36,508 0 comments 0 reactions 1 assignee Claimed by @pepelsbey View on GitHub
area: Web Components Content:WebAPI help wanted
Dominant language
Markdown
Stars
11k
Forks
23.2k
Avg merge
2d 9h
Merged PRs (30d)
331

Description

### MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals

### What specific section or headline is this issue about?

Instance properties included from ARIA

### What information was incorrect, unhelpful, or incomplete?

The issue I am reporting isn’t just for the page I’ve reported the issue for, but for all of the linked pages in the noted section as well.

`ARIAMixin` properties are implemented differently for `ElementInternals` than they are for `Element`, however, the docs describe them how they work for `Element` (i.e. as _reflecting_ content attributes). For `ElementInternals` the properties set default semantics or “implicit ARIA” for the element. There are a number of notes that correctly point that out, but the main content remains incorrect.

Some examples, starting with the `ElementsInternals` page:

> [ElementInternals.ariaAtomic](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/ariaAtomic)
> A string reflecting the [aria-atomic](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute.

From the [“`ElementInternals`: `role` property” page](
https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/role):

> The role read-only property of the [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) interface returns the [WAI-ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the element. For example, a checkbox might have [role="checkbox"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role). It reflects the role attribute; it does not return the element's implicit ARIA role, if any, unless explicitly set.

### What did you expect to see?

The docs should correctly describe how `ARIAMixin` properties for `ElementInternals` work: that they don’t reflect any attributes, but rather represent the default semantics of the custom element.

### Do you have any supporting links, references, or citations?

Relevant spec work (that does not describe how `ARIAMixin` should work for `ElementInternals`):

- https://html.spec.whatwg.org/multipage/custom-elements.html#elementinternals
- https://w3c.github.io/aria/#ARIAMixin

[The AOM explainer describes how `ElementInternals` works](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object) and notes that they do not reflect.

### Do you have anything more you want to share?

_No response_

### MDN metadata

Page report details

* Folder: `en-us/web/api/elementinternals`
* MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals
* GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/elementinternals/index.md
* Last commit: https://github.com/mdn/content/commit/8b920a5e7567dcc9d642dfbd704b0ddbe2005d30
* Document last modified: 2024-07-27T01:21:26.000Z

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.