feat: enable more granular a11y feature management #48042

codebytere · 2025-08-11T13:44:23Z

Description of Change

It's been possible to enable accessibility settings on a more granular level for some months now - after #46118 our existing a11y support methods also became more confusing as it's no longer really correct or useful to only see whether accessibility support is enabled as it could be enabled partially and the user has no insight into which parts. This adds two new methods, app.getAccessibilitySupportFeatures() and app.setAccessibilitySupportFeatures(features) allowing the user to access more granular a11y feature management.

Checklist

PR description included and stakeholders cc'd
npm test passes
tests are changed or added
relevant API documentation, tutorials, and examples are updated and follow the documentation style guide
PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added methods to enable more granular accessibility support management.

jkleinsc · 2025-08-12T21:02:21Z

docs/api/app.md

+### `app.getAccessibilitySupportFeatures()` _macOS_ _Windows_
+
+Returns `string[]` - Array of strings naming currently enabled accessibility support components.Possible values:
+
+* `nativeAPIs` - Native OS accessibility APIs integration enabled.
+* `webContents` - Web contents accessibility tree exposure enabled.
+* `inlineTextBoxes` - Inline text boxes (character bounding boxes) enabled.
+* `extendedProperties` - Extended accessibility properties enabled.
+* `screenReader` - Screen reader specific mode enabled.
+* `html` - HTML accessibility tree construction enabled.
+* `labelImages` - Accessibility support for automatic image annotations.
+* `pdfPrinting` - Accessibility support for PDF printing enabled.
+
+Notes:
+
+* The array may be empty if no accessibility modes are active.
+* Use `app.isAccessibilitySupportEnabled()` for the legacy boolean check;
+  prefer this method for granular diagnostics or telemetry.


@codebytere is there a default set of accessibility modes enabled?

@jkleinsc yes, more or less - the way we configured it after the recent refactor was that app.setAccessibilitySupportEnabled() uses ui::kAXModeComplete, which encompasses:

AXMode::kNativeAPIs | AXMode::kWebContents | AXMode::kInlineTextBoxes | AXMode::kExtendedProperties

I wasn't sure whether or how to include that in the new APIs - open to any thoughts!

@codebytere we should just document the above in the docs

@jkleinsc done in ba95cb2!

docs/api/app.md

jkleinsc

API LGTM

erickzhao · 2025-08-28T18:05:01Z

docs/api/app.md


 > [!NOTE]
-> Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
+> Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default. Calling this method will enable the following accessibility support features: `nativeAPIs`, `webContents`, `inlineTextBoxes`, and `extendedProperties`.


question: would it be more intuitive if we made setAccessibilitySupportEnabled enable all available properties?

@erickzhao i'd say no as that'd be a breaking change - this also matches upstream.

itsananderson · 2025-08-28T17:55:53Z

docs/api/app.md

+
+### `app.getAccessibilitySupportFeatures()` _macOS_ _Windows_
+
+Returns `string[]` - Array of strings naming currently enabled accessibility support components. Possible values:


I think our docs parser has the ability to generate unions of string literals, though I don't know what the exact syntax is needed to achieve that. @erickzhao pointed me to app.getPath as an API that utilizes this.

It seems like it could be useful to have a more explicit TypeScript type, so that people could get TypeScript warnings for non-exhaustive switch statements, or for passing an invalid string to setAccessibilitySupportFeatures

Actually @MarshallOfSound thinks this should be possible to get specific types for. Ref https://github.com/electron/typescript-definitions/blob/ec3384a33fa0d70d98ffc998b03c771535cc1dd9/src/utils.ts#L153-L167

We might just need to tweak/debug the syntax to get the parser to parse it correctly

Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>

reitowo

API LGTM

erickzhao

API LGTM

itsananderson

API LGTM

It'd be great to find a way to document the string literal types, but it sounds like there are limitations in the docs parser that make it infeasible right now.

If we merge this as-is, and follow up later to make getAccessibilitySupportFeatures take string literals instead of just string[], it may cause minor typechecking errors for apps that are storing values as string, but it should be an easy thing for those apps to fix the type errors when upgrading.

release-clerk · 2025-10-21T14:56:18Z

Release Notes Persisted

Added methods to enable more granular accessibility support management.

trop · 2025-10-21T14:56:53Z

I have automatically backported this PR to "39-x-y", please check out #48625

trop · 2025-10-21T14:56:59Z

I have automatically backported this PR to "38-x-y", please check out #48626

trop · 2025-10-21T14:57:02Z

I have automatically backported this PR to "37-x-y", please check out #48627

* feat: enable more granular a11y feature management * Update docs/api/app.md Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org> --------- Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>

codebytere requested a review from a team August 11, 2025 13:44

codebytere added semver/minor backwards-compatible functionality target/37-x-y PR should also be added to the "37-x-y" branch. target/38-x-y PR should also be added to the "38-x-y" branch. labels Aug 11, 2025

electron-cation bot added api-review/requested 🗳 new-pr 🌱 PR opened recently labels Aug 11, 2025

danielweck mentioned this pull request Aug 11, 2025

Electron v37 regression: app.accessibilitySupportEnabled edrlab/thorium-reader#3106

Closed

codebytere force-pushed the ax-mode-refactor branch 2 times, most recently from 2cabba1 to b413846 Compare August 12, 2025 09:04

jkleinsc reviewed Aug 12, 2025

View reviewed changes

electron-cation bot removed the new-pr 🌱 PR opened recently label Aug 18, 2025

codebytere requested a review from jkleinsc August 19, 2025 10:15

jkleinsc reviewed Aug 20, 2025

View reviewed changes

docs/api/app.md Outdated Show resolved Hide resolved

codebytere force-pushed the ax-mode-refactor branch 2 times, most recently from 49deabe to 3000f89 Compare August 25, 2025 12:57

jkleinsc reviewed Aug 25, 2025

View reviewed changes

docs/api/app.md Outdated Show resolved Hide resolved

jkleinsc reviewed Aug 25, 2025

View reviewed changes

docs/api/app.md Show resolved Hide resolved

codebytere requested a review from jkleinsc August 27, 2025 14:25

codebytere force-pushed the ax-mode-refactor branch from 9e30735 to bab9692 Compare August 27, 2025 14:39

jkleinsc reviewed Aug 27, 2025

View reviewed changes

erickzhao reviewed Aug 28, 2025

View reviewed changes

itsananderson reviewed Aug 28, 2025

View reviewed changes

github-actions bot added the target/39-x-y PR should also be added to the "39-x-y" branch. label Sep 3, 2025

codebytere requested review from erickzhao and jkleinsc September 8, 2025 07:51

codebytere and others added 2 commits October 15, 2025 12:08

feat: enable more granular a11y feature management

0d8478d

Update docs/api/app.md

d1330ec

Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>

codebytere force-pushed the ax-mode-refactor branch from bab9692 to d1330ec Compare October 15, 2025 10:09

reitowo approved these changes Oct 16, 2025

View reviewed changes

electron-cation bot removed the api-review/requested 🗳 label Oct 16, 2025

electron-cation bot added the api-review/approved ✅ label Oct 16, 2025

erickzhao approved these changes Oct 16, 2025

View reviewed changes

itsananderson approved these changes Oct 16, 2025

View reviewed changes

jkleinsc approved these changes Oct 21, 2025

View reviewed changes

jkleinsc merged commit e766d37 into main Oct 21, 2025
150 of 153 checks passed

jkleinsc deleted the ax-mode-refactor branch October 21, 2025 14:56

This was referenced Oct 21, 2025

feat: enable more granular a11y feature management #48625

Merged

feat: enable more granular a11y feature management #48626

Merged

feat: enable more granular a11y feature management #48627

Merged

trop bot added the in-flight/39-x-y label Oct 21, 2025

trop bot removed the target/39-x-y PR should also be added to the "39-x-y" branch. label Oct 21, 2025


		### `app.getAccessibilitySupportFeatures()` _macOS_ _Windows_

		Returns `string[]` - Array of strings naming currently enabled accessibility support components. Possible values:

feat: enable more granular a11y feature management #48042

feat: enable more granular a11y feature management #48042

Uh oh!

Conversation

codebytere commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Checklist

Release Notes

Uh oh!

jkleinsc Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

codebytere Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkleinsc Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

codebytere Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jkleinsc left a comment

Choose a reason for hiding this comment

Uh oh!

erickzhao Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

codebytere Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

itsananderson Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

itsananderson Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

reitowo left a comment

Choose a reason for hiding this comment

Uh oh!

erickzhao left a comment

Choose a reason for hiding this comment

Uh oh!

itsananderson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

release-clerk bot commented Oct 21, 2025

Uh oh!

trop bot commented Oct 21, 2025

Uh oh!

trop bot commented Oct 21, 2025

Uh oh!

trop bot commented Oct 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codebytere commented Aug 11, 2025 •

edited

Loading

codebytere Aug 14, 2025 •

edited

Loading