Sidebar navigation items are completely inaccessible to screen readers on Windows

[Futyn-Maker]

Search first

• I searched and no similar issues were found

Platform/OS

Windows

OS version

Windows 11 Pro 10.0.22631

Hiddify Version

4.1.1 / 4.1.2 dev (built from source)

What Happened?

The desktop sidebar navigation (Home, Profiles, Settings, Logs, About) is completely invisible to the NVDA (and maybe other) screen reader on Windows. When using screen readers, these navigation items:

• Cannot be found via NVDA object navigation (Insert+Numpad arrows)
• Are not announced when receiving keyboard focus via Tab
• Do not seem to be appear in the Windows UI Automation (UIA) accessibility tree at all

The items are focusable through the app's custom keyboard handling (press Left arrow to enter the sidebar, then Tab to move between items), and can even be activated by pressing Enter/Space. However, NVDA remains completely silent throughout — no element names, no roles, no state information. A blind user must memorize the order of items and navigate by counting Tab presses.

For comparison, other interactive elements in the app (the connection button, "View all profiles" link, etc.) are properly announced by NVDA.

Minimal Reproducible Example (MRE)

1. Launch Hiddify on Windows with NVDA screen reader running
2. Press Left arrow to move focus into the sidebar navigation area
3. Press Tab repeatedly to move through sidebar items (Home, Profiles, Settings, Logs, About)
4. Observe that NVDA announces nothing at each Tab stop — complete silence
5. For comparison: press Right arrow to move to the content area, then Tab to the connection button — NVDA correctly announces "Click to connect, button"

Expected Behavior

When navigating sidebar items with Tab, NVDA should announce each item's name and role, for example: "Home, Tab 1 of 5, button, selected" — similar to how the bottom navigation bar works on mobile, and similar to how other interactive elements in the app are announced.

Additional Context

I tried to conduct a small analysis of the problem and fix it myself, but I didn't succeed. Here is what I found.

The desktop sidebar uses Flutter's NavigationRail widget (lib/core/router/adaptive_layout/my_adaptive_layout.dart). This widget seem to have a confirmed upstream accessibility deficiency.

I try to do the following:

• Wrapping destination icons in Semantics(button: true, enabled: true) — flags merge correctly in the semantics tree but are still not exposed to UIA
• Adding Semantics(label: ..., button: true) to the icon's semanticLabel — blocked by NavigationRail's internal Semantics(explicitChildNodes: true) barrier
• Placing a TextButton in NavigationRail's leading slot — also invisible to NVDA, confirming the entire NavigationRail subtree is inaccessible

Application Config Options

No response

Relevant log output

No response

Are you willing to submit a PR? If you know how to fix the bug.

• I'm willing to submit a PR (Thank you!)

[m13v]

Flutter's NavigationRail has this known accessibility gap where the semantics tree doesn't properly expose to platform accessibility providers. the issue is that NavigationRail uses internal Semantics nodes with explicitChildNodes: true, which creates a barrier that prevents child semantics from reaching the platform layer (UIA on Windows).

we ran into similar problems when trying to automate Flutter apps through Windows UI Automation. the workaround that works: replace NavigationRail with a custom widget built from plain Column + InkWell/GestureDetector, each wrapped in Semantics(label: 'Home', button: true, onTap: ...). this bypasses NavigationRail's internal semantics barrier and the buttons appear correctly in the UIA tree.

another approach: use SemanticsService.announce() to manually broadcast navigation changes, though this is more of a band-aid. the real fix needs to come from Flutter upstream or from replacing the widget.

for testing, Accessibility Insights for Windows is the best tool to verify what the UIA tree actually exposes. inspect.exe works too but Accessibility Insights shows live updates as focus changes.

[m13v]

fwiw we do a lot of Windows UI Automation testing, our element interaction layer that handles UIA tree traversal and the quirks of different widget frameworks: https://github.com/mediar-ai/terminator/blob/main/crates/terminator/src/element.rs

[Futyn-Maker]

Thanks for the confirmation. I have a bit of experience in Flutter development, but I came to the same conclusion.

I'm leaning towards the idea that a custom widget would be the best solution here, unless someone feels competent enough to fix the bug in Flutter upstream :) How acceptable is this for the Hiddify maintainers?

[m13v]

a custom widget wrapping NavigationRail with proper Semantics annotations is probably the fastest path. you can keep the NavigationRail visuals but add a Semantics widget around each item with label, role, and onTap. that way screen readers see it correctly without needing the upstream Flutter fix. the Flutter accessibility team has been slow on NavigationRail fixes, so this is likely more reliable than waiting.