Repository navigation
Description
Platform: Windows (UI Automation). Version: accesskit_windows 0.34.0 through current main.
Problem
The Windows adapter gives a heading's level to UIA only as UIA_LevelPropertyId and as level= in UIA_AriaPropertiesPropertyId. It never sets UIA_HeadingLevelPropertyId (30173), so every heading reports the default, HeadingLevel_None.
Narrator's heading navigation (scan mode H / Shift+H and the headings list) goes by HeadingLevel. So AccessKit headings are announced as "heading", but Narrator can't move to them or list them.
To reproduce, put a Node::new(Role::Heading) with set_label("Inbox") and set_level(2) in any tree, then read UIA_HeadingLevelPropertyId on it with a UIA client. You get HeadingLevel_None (80050) where you'd expect HeadingLevel2 (80052).
What Chromium does
AXPlatformNodeWin::GetPropertyValueImpl answers UIA_HeadingLevelPropertyId with AXHierarchicalLevelToUIAHeadingLevel(role, hierarchical_level) (ui/accessibility/platform/ax_platform_node_win.cc). For a heading with level 1 to 9 that returns HeadingLevel1 + level - 1. For anything else, including a level above 9 (UIA has no enum value for those), it returns HeadingLevel_None.
Proposed implementation
Only adapters/windows/src/node.rs changes:
- A
heading_level(&self) -> Option<i32>method next tolevel(). It returnsHeadingLevel1.0 + level - 1when the role isRole::Headingandlevel()is in1..=9, andNoneotherwise. WithNone, UIA keeps its default,HeadingLevel_None, which matches Chromium for non-headings and out-of-range levels. - A
(UIA_HeadingLevelPropertyId, heading_level)entry in the property table, after(UIA_LevelPropertyId, level). - A test in
adapters/windows/src/tests/built likesimple.rs. It reads the property throughIUIAutomationfor a level-2 heading (HeadingLevel2), a level-12 heading (HeadingLevel_None) and a label (HeadingLevel_None).
The other adapters don't need anything from this. macOS headings are covered separately in #830.
We carry exactly this change as a local patch on 0.34.0, and the test above passes on Windows CI. I can share the diff if that helps.
This issue was drafted with the help of an AI assistant. The behaviour and the Chromium reference were checked against the sources.
Activity
squalorso commentedon Oct 28, 2026
Thanks for writing this up — exposing a heading's level on Windows is worth doing, and the Chromium reference is the right one. Two things from testing on Windows would help the change land correctly for more screen readers.
1.
levelis zero-based, so the formula is off by one.AccessKit's
levelis zero-based. The docs call this out on theLevelproperty (accesskit/src/lib.rs): "aria-levelis one-based, while this property is zero-based." So a level-1 heading haslevel() == 0.With that,
HeadingLevel1 + level - 1maps a level-1 heading (level 0) toHeadingLevel1 - 1, i.e.HeadingLevel_None, and a level-2 heading toHeadingLevel1. The mapping that matches the zero-based semantics is:This is also consistent with the adapter's existing
UIA_LevelPropertyIdmapping, which already adds one tolevel(adapters/windows/src/node.rs,level()). (In the repro,set_level(2)is an ARIA level-3 heading under the zero-based rule, which is probably not what's intended.)2.
HeadingLevelalone doesn't reach NVDA.Narrator and Chromium navigate headings by
UIA_HeadingLevelPropertyId, so this change fixes them. NVDA, however, doesn't readHeadingLevelat all — it takes a heading's level from theUIA_StyleIdAttributeIdtext attribute (StyleId_Heading1…StyleId_Heading9) on the heading's text range, both for reading and for theHquick-nav key (NVDAObjects/UIA/__init__.pyandbrowseMode.py). So after this issue, AccessKit headings would work in Narrator but still be silent under NVDA.This matches Microsoft Word, the usual parity reference. Measured through UIA, a Heading N paragraph's text range carries
StyleId_HeadingN(Heading 1 →StyleId_Heading1, Heading 2 →StyleId_Heading2, …) together withStyleName("Heading 1", …). That StyleId is what drives theHkey and structured reading in Word under NVDA.So it would be worth exposing both:
UIA_HeadingLevelPropertyId(this issue, for Narrator and Chromium) andUIA_StyleIdAttributeIdon the heading's text range (for NVDA). JAWS also doesn't navigate these headings today; I can check whether it needs the StyleId the same way.I'm set up on Windows with NVDA 2026.2 and JAWS 2026 and can test any patch against both, and share the UIA reproductions if that helps.
Posted with the help of an AI assistant; the measurements and the NVDA and Chromium references were checked against the sources.
ChacaPatrick commentedon Nov 12, 2026
+1 on this issue. We hit the same thing with a GPUI app on Windows: headings report
AriaRole=headingandLevel, butHeadingLevelstaysHeadingLevel_None, so Narrator's headings list skips them.We implemented the plan from the description on current
main, using the zero-based mapping from the comment above:We added it to the property table after
(UIA_LevelPropertyId, level), plus a test inadapters/windows/src/tests/heading.rs. The test readsUIA_HeadingLevelPropertyIdthroughIUIAutomation:HeadingLevel1HeadingLevel9HeadingLevel_NoneHeadingLevel_NoneHeadingLevel_NoneThe test fails without the change and passes with it.
cargo fmtandcargo clippy -p accesskit_windows --all-targets -D warningsare clean.simple::focusfails locally with and without the change, which matches the focus warning in CONTRIBUTING.md. We're happy to share the branch or open a PR if a maintainer would like one.One request, if you're open to it: GPUI currently pins
accesskit_windows0.34. If this could also go out as a 0.34.x patch release, downstream apps that can't move to 0.35 yet would get the fix through a plaincargo update. We understand if you only release frommain.