Skip to content

Windows: expose a heading's level as UIA HeadingLevel #840

Open

Description

@wingleeio

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:

  1. A heading_level(&self) -> Option<i32> method next to level(). It returns HeadingLevel1.0 + level - 1 when the role is Role::Heading and level() is in 1..=9, and None otherwise. With None, UIA keeps its default, HeadingLevel_None, which matches Chromium for non-headings and out-of-range levels.
  2. A (UIA_HeadingLevelPropertyId, heading_level) entry in the property table, after (UIA_LevelPropertyId, level).
  3. A test in adapters/windows/src/tests/ built like simple.rs. It reads the property through IUIAutomation for 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

  1. squalorso commented on Oct 28, 2026

    @squalorso

    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. level is zero-based, so the formula is off by one.

    AccessKit's level is zero-based. The docs call this out on the Level property (accesskit/src/lib.rs): "aria-level is one-based, while this property is zero-based." So a level-1 heading has level() == 0.

    With that, HeadingLevel1 + level - 1 maps a level-1 heading (level 0) to HeadingLevel1 - 1, i.e. HeadingLevel_None, and a level-2 heading to HeadingLevel1. The mapping that matches the zero-based semantics is:

    HeadingLevel1 + level   for level in 0..=8, else HeadingLevel_None
    

    This is also consistent with the adapter's existing UIA_LevelPropertyId mapping, which already adds one to level (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. HeadingLevel alone doesn't reach NVDA.

    Narrator and Chromium navigate headings by UIA_HeadingLevelPropertyId, so this change fixes them. NVDA, however, doesn't read HeadingLevel at all — it takes a heading's level from the UIA_StyleIdAttributeId text attribute (StyleId_Heading1 … StyleId_Heading9) on the heading's text range, both for reading and for the H quick-nav key (NVDAObjects/UIA/__init__.py and browseMode.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 with StyleName ("Heading 1", …). That StyleId is what drives the H key and structured reading in Word under NVDA.

    So it would be worth exposing both: UIA_HeadingLevelPropertyId (this issue, for Narrator and Chromium) and UIA_StyleIdAttributeId on 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.

  2. ChacaPatrick commented on Nov 12, 2026

    @ChacaPatrick

    +1 on this issue. We hit the same thing with a GPUI app on Windows: headings report AriaRole=heading and Level, but HeadingLevel stays HeadingLevel_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:

    fn heading_level(&self) -> Option<i32> {
        // Like Chromium, only headings with a level that UIA can represent
        // (HeadingLevel1 to HeadingLevel9) report one. For everything else,
        // UIA falls back to HeadingLevel_None. AccessKit levels are zero-based.
        if self.node.role() != Role::Heading {
            return None;
        }
        match self.node.level()? {
            level @ 0..=8 => Some(HeadingLevel1.0 + level as i32),
            _ => None,
        }
    }

    We added it to the property table after (UIA_LevelPropertyId, level), plus a test in adapters/windows/src/tests/heading.rs. The test reads UIA_HeadingLevelPropertyId through IUIAutomation:

    • level 0 → HeadingLevel1
    • level 8 → HeadingLevel9
    • level 9 → HeadingLevel_None
    • a heading with no level → HeadingLevel_None
    • a paragraph with a level → HeadingLevel_None

    The test fails without the change and passes with it. cargo fmt and cargo clippy -p accesskit_windows --all-targets -D warnings are clean. simple::focus fails 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_windows 0.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 plain cargo update. We understand if you only release from main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions