diff --git a/public/og-default.png b/public/og-default.png index ded2aecd..499db2fa 100644 Binary files a/public/og-default.png and b/public/og-default.png differ diff --git a/public/og/checklist.png b/public/og/checklist.png index 91b48a7a..5f536acd 100644 Binary files a/public/og/checklist.png and b/public/og/checklist.png differ diff --git a/public/og/spec.png b/public/og/spec.png index d95fcbb4..0d6e626d 100644 Binary files a/public/og/spec.png and b/public/og/spec.png differ diff --git a/public/og/spec/accessibility.png b/public/og/spec/accessibility.png index 31562dd7..bf6ec858 100644 Binary files a/public/og/spec/accessibility.png and b/public/og/spec/accessibility.png differ diff --git a/public/og/spec/accessibility/inert-attribute.png b/public/og/spec/accessibility/inert-attribute.png new file mode 100644 index 00000000..73803745 Binary files /dev/null and b/public/og/spec/accessibility/inert-attribute.png differ diff --git a/src/content/changelog/2026-06-26-inert-attribute.md b/src/content/changelog/2026-06-26-inert-attribute.md new file mode 100644 index 00000000..5adb966c --- /dev/null +++ b/src/content/changelog/2026-06-26-inert-attribute.md @@ -0,0 +1,8 @@ +--- +title: "Added the inert attribute" +date: "2026-06-26" +type: added +relatedSlugs: [inert-attribute] +--- + +Added a page on [the inert attribute](/spec/accessibility/inert-attribute/), the HTML boolean attribute that makes a subtree non-interactive — removing it from the tab order and the accessibility tree at once. It replaces fragile focus-trap scripting when an overlay is open, and has been Baseline across browsers since April 2023. diff --git a/src/content/spec/accessibility/focus-indicators.md b/src/content/spec/accessibility/focus-indicators.md index a57322aa..ea2e4dcb 100644 --- a/src/content/spec/accessibility/focus-indicators.md +++ b/src/content/spec/accessibility/focus-indicators.md @@ -6,7 +6,7 @@ summary: "Whenever a control receives keyboard focus, the page must show a clear status: required order: 50 appliesTo: [all] -relatedSlugs: [keyboard-navigation, color-contrast] +relatedSlugs: [keyboard-navigation, color-contrast, inert-attribute] updated: "2026-05-29T09:13:20.000Z" sources: - title: "WCAG 2.4.7 — Focus Visible (Level AA)" diff --git a/src/content/spec/accessibility/inert-attribute.md b/src/content/spec/accessibility/inert-attribute.md new file mode 100644 index 00000000..3adffe0b --- /dev/null +++ b/src/content/spec/accessibility/inert-attribute.md @@ -0,0 +1,64 @@ +--- +title: "The inert attribute" +slug: inert-attribute +category: accessibility +summary: "When an overlay is open, the content behind it should be unreachable — not just dimmed. The inert attribute removes a subtree from tab order and the accessibility tree at once, replacing fragile focus-trap JavaScript." +status: recommended +order: 65 +appliesTo: [all] +relatedSlugs: [keyboard-navigation, focus-indicators, skip-links, native-interactive-elements] +updated: "2026-06-26T09:00:00.000Z" +sources: + - title: "HTML Standard — The inert attribute" + url: "https://html.spec.whatwg.org/multipage/interaction.html#the-inert-attribute" + publisher: "WHATWG" + - title: "ARIA Authoring Practices Guide — Dialog (Modal) Pattern" + url: "https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/" + publisher: "W3C" + - title: "MDN — inert" + url: "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert" + publisher: "MDN" +--- + +## What it is + +`inert` is a boolean global attribute that makes an element and all of its descendants non-interactive. An inert subtree cannot receive focus, cannot be clicked, is skipped by the tab order, is removed from the accessibility tree, and is ignored by find-in-page. It is defined in the WHATWG HTML Standard and has been Baseline Widely Available across browsers since April 2023. + +The canonical use is managing background content. When a modal dialog, slide-out menu, or off-canvas panel is open, everything behind it should be genuinely unreachable — not merely greyed out, but inert to the keyboard and to assistive technology. + +## Why it matters + +Before `inert`, keeping focus inside an open dialog meant fragile scripting: trapping the Tab key, tracking the first and last focusable element, and toggling `tabindex="-1"` plus `aria-hidden` on every background node — then undoing it all on close. Miss one path and a keyboard user tabs out of the dialog into hidden content they cannot see. That is a focus-order failure (WCAG 2.4.3) and a likely keyboard trap. + +`inert` collapses that into one declarative attribute. It removes the subtree from the tab order and the accessibility tree together, so keyboard and screen-reader users get the same boundary the visual design implies. + +## How to implement + +Mark the container that should become unreachable, and clear it when the content is active again: + +```html +
+ +
+
+ +
+``` + +- A modal `` opened with `showModal()` makes the rest of the document inert automatically — you do not need to set the attribute yourself. Reach for `inert` on non-`` patterns: custom menus, off-screen navigation, multi-step panels. +- Obscure inert content visually (a backdrop or dimming) so sighted users are not confused by content they cannot use. The spec asks authors to do this. +- Toggle it from script as state changes: `el.inert = true`. +- Use `disabled`, not `inert`, to switch off an individual form control. + +## Common mistakes + +- Using `aria-hidden` alone for background content — it hides from screen readers but leaves elements focusable, so keyboard focus still escapes. +- Marking content inert while leaving it fully visible and undimmed. +- Forgetting to remove `inert` when the overlay closes, stranding the whole page. +- Applying `inert` to the dialog itself instead of to the background. + +## Verification + +- Open each overlay and press Tab repeatedly: focus must cycle only within the active region and never reach a background control. +- With a screen reader running, background landmarks and headings should not be announced while the overlay is open. +- Use find-in-page — text inside an inert subtree must not be found. diff --git a/src/content/spec/accessibility/keyboard-navigation.md b/src/content/spec/accessibility/keyboard-navigation.md index 9ccd7a8e..efe88a82 100644 --- a/src/content/spec/accessibility/keyboard-navigation.md +++ b/src/content/spec/accessibility/keyboard-navigation.md @@ -6,7 +6,7 @@ summary: "Every interactive element on the page must be reachable and operable w status: required order: 40 appliesTo: [all] -relatedSlugs: [focus-indicators, skip-links, semantic-html] +relatedSlugs: [focus-indicators, skip-links, semantic-html, inert-attribute] updated: "2026-05-29T09:13:20.000Z" sources: - title: "WCAG 2.1.1 — Keyboard (Level A)" diff --git a/src/content/spec/accessibility/native-interactive-elements.md b/src/content/spec/accessibility/native-interactive-elements.md index a0d36669..3d53b316 100644 --- a/src/content/spec/accessibility/native-interactive-elements.md +++ b/src/content/spec/accessibility/native-interactive-elements.md @@ -6,7 +6,7 @@ summary: "Prefer native HTML interactive elements —