# ARIA Widget Patterns

Use these patterns only when no semantic HTML equivalent exists.

## Criteria

| Standard | Criteria                                             |
| -------- | ---------------------------------------------------- |
| WCAG 2.2 | 4.1.2 Name, Role, Value (A)                          |
| RGAA 4.1 | 7.1 Script compatibility with assistive technologies |

### Name, Role, Value — WCAG 4.1.2 (A) / RGAA 7.1

All UI components must have programmatically determinable: **name** (accessible name), **role** (semantic role), **states/properties** (communicated to assistive technology). Use semantic HTML first. Add ARIA only when needed. Keep `aria-expanded`, `aria-selected`, `aria-checked`, etc. updated as state changes.

### RGAA 7.1 — Script compatibility with assistive technologies (Level A)

Is each script, if necessary, compatible with assistive technologies?

#### Test 7.1.1 — Script-generated components have accessible name, role, value

Does each script that generates or controls a UI component meet one of these conditions?

- Name, role, value, settings, and state changes are accessible to assistive technologies via an accessibility API;
- An accessible UI component providing the same functionality is present in the page;
- An accessible alternative provides the same functionality.

Methodology:

1. Find all UI components generated or controlled via JavaScript.
2. Verify that:
   - The component has a role consistent with its usage (generally a button or link);
   - The component has an explicit name;
   - The component name is consistent with the state of the controlled functionality or content (e.g., for a show/hide function).
3. Otherwise, verify the presence of an accessible UI component providing the same functionality.
4. Otherwise, verify the presence of an accessible alternative providing the same functionality.
5. If so, the test is validated.

#### Test 7.1.2 — Script-generated components are correctly rendered by assistive technologies

Does each script that generates or controls a UI component meet one of these conditions?

- The UI component is correctly rendered by assistive technologies;
- An accessible alternative provides the same functionality.

Methodology:

1. For each component that passed test 7.1.1, verify it is correctly rendered by assistive technologies.
2. Otherwise, verify an accessible alternative to the component provides the same functionality.
3. If so, the test is validated.

#### Test 7.1.3 — Component has relevant name and role, accessible name contains visible label

Does each script that generates or controls a UI component verify these conditions (except in special cases)?

- The component has a relevant name;
- The accessible name contains at least the visible label;
- The component has a relevant role.

Methodology:

1. For each component that passed test 7.1.1, verify the component has:
   - A relevant name (visible label);
   - A relevant role.
2. If the component has an accessible name, verify it is relevant and contains at least the visible label.
3. If so, the test is validated.

#### Cas particuliers

Special cases for test 7.1.3:

- Punctuation and capital letters in the visible label text may be ignored in the accessible name without consequence.
- When visible label text serves as a symbol: the text must not be interpreted literally in the accessible name. The name must express the function conveyed by the symbol (e.g., "B" in a text editor should have accessible name "Bold", ">" may mean "Next" or "Play video" depending on context). Exception: mathematical symbols may be taken literally (e.g., "A>B").

Note: if the visible label represents a mathematical expression, mathematical symbols may be used literally as the accessible name (e.g., "A>B").

#### Notes techniques

Criterion 7.1 implements the concept of "compatible with assistive technologies" as defined by WCAG, as well as the use of WAI-ARIA to make a component or functionality accessible. Correct WAI-ARIA usage is verified via tests 7.1.1, 7.1.2, 7.1.3.

Important note: in an HTML5 environment, many components may require JavaScript to function. Providing an alternative to a JavaScript component that cannot be made accessible must use a method specific to that component, allowing it to be replaced by an accessible alternative (and reactivated). Disabling JavaScript for the entire page is not accepted as a valid method, unless it does not compromise other components.

#### WCAG references

- 2.5.3 Label in Name (A)
- 4.1.2 Name, Role, Value (A)

## Patterns

**Disclosure (Accordion):**

```html
<button aria-expanded="false" aria-controls="panel-1">Section Title</button>
<div id="panel-1" hidden>Panel content</div>
```

**Tabs:**

```html
<div role="tablist" aria-label="Settings">
  <button role="tab" aria-selected="true" aria-controls="p1" id="t1">General</button>
  <button role="tab" aria-selected="false" aria-controls="p2" id="t2" tabindex="-1">Privacy</button>
</div>
<div role="tabpanel" id="p1" aria-labelledby="t1">...</div>
<div role="tabpanel" id="p2" aria-labelledby="t2" hidden>...</div>
```

Arrow keys move between tabs. Only selected tab has `tabindex="0"`.

**Menu:**

```html
<button aria-haspopup="menu" aria-expanded="false">Options</button>
<ul role="menu">
  <li role="menuitem" tabindex="-1">Edit</li>
  <li role="menuitem" tabindex="-1">Delete</li>
</ul>
```

**Alert Dialog:**

```html
<div role="alertdialog" aria-modal="true" aria-labelledby="title" aria-describedby="desc">
  <h2 id="title">Confirm Delete</h2>
  <p id="desc">This cannot be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>
```