Screen reader Accessibility Improvements by matalvernaz · Pull Request #8497 · Sonarr/Sonarr

matalvernaz · 2026-03-26T19:03:27Z

Sonarr is a great tool for me even though I'm completely blind. Right now the accessibility kinda sucks though so I wanted to try and make it better.

What's fixed

Buttons weren't labeled for my screen reader, aria labels have been added to fix that. Tables were unclear, and have been clarified a bit; at least from what I can tell from limited local testing. More images have been given alt text, so it doesn't just say iconx360.png or something equally unhelpful. Translations updated for aria labels.

Changes

IconButton: removed hardcoded 'Table Options Button' label that was announced on every icon button regardless of purpose; all call sites now have a meaningful aria-label; icon marked aria-hidden
Modal/ModalHeader: added role="dialog", aria-modal, and aria-labelledby so screen readers announce the modal title when it opens
MonitorToggleButton: added aria-label alongside title (NVDA reads title inconsistently)
TablePager: first/previous/next/last page links now have descriptive aria-label; pagination icons marked aria-hidden
PageSidebar: outer div changed to nav with aria-label so it appears as a navigation landmark
PageSidebarItem: aria-current="page" on the active link; sidebar icons marked aria-hidden
TableHeaderCell: aria-sort (ascending/descending/none) and scope="col" on sortable header cells; sort icon marked aria-hidden
en.json: added MainNavigation and PagerGoTo* translation keys

No visual changes.

- IconButton: remove hardcoded 'Table Options Button' aria-label that was announced on every icon button regardless of purpose; callers now supply their own aria-label via props; icon marked aria-hidden - Modal/ModalHeader: add role="dialog", aria-modal, and aria-labelledby via a new ModalContext so screen readers announce the modal title on open - MonitorToggleButton: add aria-label alongside title for NVDA compatibility - TablePager: add descriptive aria-label to first/previous/next/last page links; pagination icons marked aria-hidden - PageSidebar: change wrapper div to <nav> with aria-label so it appears as a navigation landmark - PageSidebarItem: add aria-current="page" on the active link; sidebar icons marked aria-hidden - TableHeaderCell: add aria-sort (ascending/descending/none) and scope="col" to sortable headers; sort icon marked aria-hidden - en.json: add MainNavigation and PagerGoTo* translation keys Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Every IconButton that previously relied on the hardcoded fallback 'Table Options Button' label now has a meaningful, context-specific aria-label. Labels use existing translate() keys where available and plain strings where translate is not imported in the file. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

stevietv

Some strings are missing the translations, added the suggestions but please check they are the correct keys. also ensure translate is imported where it isn't

stevietv · 2026-03-26T20:40:33Z

          return (
            <TableRowCell key={name} className={styles.details}>
-              <IconButton name={icons.INFO} onPress={handleDetailsPress} />
+              <IconButton name={icons.INFO} aria-label="Details" onPress={handleDetailsPress} />


Suggested change

<IconButton name={icons.INFO} aria-label="Details" onPress={handleDetailsPress} />

<IconButton name={icons.INFO} aria-label={translate('Details')} onPress={handleDetailsPress} />

stevietv · 2026-03-26T20:40:57Z

        />

-        <IconButton name={icons.ADD} onPress={handleAddPress} />
+        <IconButton name={icons.ADD} aria-label="Add" onPress={handleAddPress} />


Suggested change

<IconButton name={icons.ADD} aria-label="Add" onPress={handleAddPress} />

<IconButton name={icons.ADD} aria-label={translate('Add')} onPress={handleAddPress} />

stevietv · 2026-03-26T20:44:32Z

            <IconButton
              className={styles.editButton}
              name={icons.EDIT}
+              aria-label="Edit"


Suggested change

aria-label="Edit"

aria-label={translate('Edit')}

stevietv · 2026-03-26T20:44:47Z

        {isNew ? null : (
          <IconButton
            name={icons.REMOVE}
+            aria-label="Remove"


Suggested change

aria-label="Remove"

aria-label={translate('Remove')}

stevietv · 2026-03-26T20:48:42Z

                onTableOptionChange={onTableOptionChange}
              >
-                <IconButton name={icons.ADVANCED_SETTINGS} />
+                <IconButton name={icons.ADVANCED_SETTINGS} aria-label="Advanced Settings" />


Suggested change

<IconButton name={icons.ADVANCED_SETTINGS} aria-label="Advanced Settings" />

<IconButton name={icons.ADVANCED_SETTINGS} aria-label={translate('AdvancedSettings')} />

assuming AdvancedSettings is a translation key

stevietv · 2026-03-26T20:50:38Z

        <SpinnerIconButton
          name={icons.REFRESH}
          spinningName={icons.REFRESH}
+          aria-label="Run"


Suggested change

aria-label="Run"

aria-label={translate('Run')}

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

stevietv · 2026-03-27T06:57:04Z


 export const urlBase = window.Sonarr.urlBase;
-export const apiRoot = '/api/v5'; // window.Sonarr.apiRoot;
+export const apiRoot = window.Sonarr.apiRoot;


why are you making this change in a screen reader accessibilty PR? we are not ready for this change until the full api is migrated to v5, this change essentially puts us back to v3.

stevietv · 2026-03-27T06:57:48Z

please remove this added docker file, I assume this is for your testing only.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

- Revert fetchJson.ts apiRoot back to hardcoded /api/v5 per reviewer request; dynamic apiRoot change is premature until full v5 API migration - Remove Dockerfile (was testing artifact, not intended for the PR) Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

- Underlay link now announces series title (existing) or "Add {title}" (new) - TVDB external link gets aria-label "View {title} on TVDB"; icon marked aria-hidden - Added ViewSeriesOnTvdb translation key to en.json Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

matalvernaz · 2026-03-27T07:38:10Z

Hey, I just wanted to apologize for my last very messy pr, and for the AI code submissions in general. I have a bit of coding knowledge and access to an AI, but have never really used github which is a dangerous combo in the best case. I was adding a new show and getting annoyed, not really doing any research whatsoever before I made the PR in the first place. I really appreciate that people are willing to possibly look into adding this, and want to make it as easy as possible for everybody involved. If there's anything else I can do to help with that including screwing off and staying out of the way, please let me know.

stevietv · 2026-03-27T08:27:27Z

Hey, I just wanted to apologize for my last very messy pr, and for the AI code submissions in general. I have a bit of coding knowledge and access to an AI, but have never really used github which is a dangerous combo in the best case. I was adding a new show and getting annoyed, not really doing any research whatsoever before I made the PR in the first place. I really appreciate that people are willing to possibly look into adding this, and want to make it as easy as possible for everybody involved. If there's anything else I can do to help with that including screwing off and staying out of the way, please let me know.

In my opinion the aria-improvements are very welcome, indeed sonarr doesn't have much A11y consideration in place.
It's important when contributing that you're able to test and verify that the changes you've made are working, especially when claude is doing the heavy lifting.

matalvernaz · 2026-03-27T08:41:27Z

I'm testing locally on my instance with firefix, chrome and edge using both jaws and NVDA. I'm still adding missing labels when I find them but it's definitely better.

markus101

I agree, the changes are very welcomed, but Claude needs to have it's hand-held to actually do things correctly, there are several issues that would be caught by the linter if that was run prior to submission and some random things that were changed for seemingly no reason like the API root change Stevie caught and another because it decided UI settings was using the wrong path.

markus101 · 2026-03-28T19:54:44Z

      ? icons.SORT_ASCENDING
      : icons.SORT_DESCENDING;

+  const ariaSortValue = isSorting


This fails linting. Do not nest ternary expressions

Something like this would be much more readable.

const ariaSortValue = useMemo(() => { if (!isSortable) { return undefined; } if (!isSorting) { return 'none'; } return sortDirection === sortDirections.ASCENDING ? 'ascending' : 'descending'; }, [isSorting, sortDirection, isSortable]);

markus101 · 2026-03-28T19:55:13Z


+  const ariaSortValue = isSorting
+    ? sortDirection === sortDirections.ASCENDING
+      ? ('ascending' as const)


Why is everything using as const?

markus101 · 2026-03-28T19:56:38Z

 }

-const PATH = '/settings/ui';
+const PATH = '/config/ui';


This is wrong.

markus101 · 2026-03-28T19:57:38Z

                    onTableOptionChange={onTableOptionChange}
                  >
-                    <IconButton name={icons.ADVANCED_SETTINGS} />
+                    <IconButton name={icons.ADVANCED_SETTINGS} aria-label="Advanced Settings" />


This should be translated.

Addresses PR review from markus101: nested ternary failed linting, replaced with useMemo block per suggested pattern. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Addresses PR review from markus101: hardcoded string replaced with translate('AdvancedSettings'); import added. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

The /config/ui path was incorrect; /settings/ui is consistent with all other settings hooks (general, mediamanagement, naming, etc.). Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

matalvernaz · 2026-03-29T07:40:18Z

I've addressed these fixes, and everything seems to be working in my test instance. I've tested with chrome and firefox, jaws and NVDA. Everything seems to be working and the logs aren't screaming at me, so there's hope.

stevietv · 2026-03-29T07:54:45Z

I've addressed these fixes, and everything seems to be working in my test instance. I've tested with chrome and firefox, jaws and NVDA. Everything seems to be working and the logs aren't screaming at me, so there's hope.

just want to make sure you also ran yarn lint to check it complies?

Remove event.preventDefault() from label onClick so screen readers receive a real DOM state change when a checkbox is toggled. ShiftKey is captured via a ref on the label click (which fires before onChange) so shift-range-select on table rows continues to work. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Auto-fix prettier formatting and import sort order across all files flagged by yarn lint. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

matalvernaz · 2026-03-29T08:13:23Z

Yes, just ran that and fixed a bunch of formatting issues.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

markus101 · 2026-03-29T21:23:20Z

Please remove all the recent changes around build scripts and CI. GitHub actions already runs linting as part of the build process.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

matalvernaz · 2026-03-29T21:26:22Z

Done. Sorry about that, claude ran along with an idea I wasn't wanting.

markus101

Shift clicking ranges of check inputs is broken and I'm not really sure what the purpose of the modal header ID is.

markus101 · 2026-04-12T22:19:07Z

 import styles from './CheckInput.css';

-interface ChangeEvent<T = Element> extends SyntheticEvent<T, MouseEvent> {
+interface ChangeEvent<T = Element> extends React.SyntheticEvent<T, MouseEvent> {


This should use SyntheticEvent directly, like it did before.

markus101 · 2026-04-12T22:20:44Z

-    },
-    [isDisabled, toggleChecked]
-  );
+  const handleLabelClick = useCallback((event: React.MouseEvent) => {


Same with MouseEvent

markus101 · 2026-04-12T22:22:49Z

    [name, value, checkedValue, uncheckedValue, onChange]
  );

-  const handleClick = useCallback(


This broke using shift-clicking to change a whole range of check inputs, why was it changed?

markus101 · 2026-04-12T22:24:27Z

    return null;
  }

+  const headerId = `${modalId}-header`;


What is the purpose of the headerId? Seems like it's just passed to the header's div, but not clear what that actually provides.

If the modal needs to pass an ID down then it should just pass the ID, such as modalId, then consumers can use it as needed, right now if the body also needed an ID then you'd have to pass bodyId even though it's the same ID and a different suffix.

If this isn't needed then it should be removed though.

the headerId is what aria-labelledby on the dialog points to (line 184), and ModalHeader sets the same id on the visible h2 through ModalContext. without that link the dialog has no accessible name, so screen readers just say "dialog" with nothing else.

I can rename it to something less generic like modalHeaderId if that reads better, or pass the raw modalId through context and have ModalHeader build its own suffix. let me know which you'd prefer and I'll change it.

Gotcha, I think this actually makes sense as-is after looking at it again so we don't potentially create different header IDs in different places.

markus101 · 2026-04-12T22:25:47Z

+    if (!isSortable) {
+      return undefined;
+    }
+    if (!isSorting) {


New line needed before if block

markus101 · 2026-04-12T22:25:55Z

+    if (!isSorting) {
+      return 'none';
+    }
+    return sortDirection === sortDirections.ASCENDING


And before this return

markus101 · 2026-04-12T22:26:20Z

      {children}

-      {isSorting && <Icon name={sortIcon} className={styles.sortIcon} />}
+      {isSorting && (


Use ternary instead of &&

CheckInput: revert label onClick to handleClick with preventDefault so event.nativeEvent.shiftKey is read directly in onChange, restoring shift-range selection on table check inputs. Drops the shiftKeyRef hack and the React.SyntheticEvent/React.MouseEvent qualifications. TableHeaderCell: blank lines before if/return inside the useMemo, ternary with null instead of && for the sort icon. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

matalvernaz and others added 3 commits March 26, 2026 11:42

Fix: sort PagerGoTo* translation keys into correct alphabetical position

012aa40

stevietv reviewed Mar 26, 2026

View reviewed changes

stevietv suggested changes Mar 26, 2026

View reviewed changes

matalvernaz and others added 4 commits March 26, 2026 14:08

Fix: use translate() for aria-labels instead of hardcoded strings

0d00eb9

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Fix: TablePager totalPages undefined type error in translate call

0ab10c4

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Fix: use dynamic apiRoot from window.Sonarr instead of hardcoded v5

22ce1ef

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Fix: build frontend in production mode for content-hashed filenames

6659b2b

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

stevietv suggested changes Mar 27, 2026

View reviewed changes

matalvernaz and others added 3 commits March 27, 2026 00:07

Fix: use v4 config/ui endpoint instead of v5 settings/ui

e81fa85

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

markus101 requested changes Mar 28, 2026

View reviewed changes

matalvernaz and others added 3 commits March 28, 2026 16:31

Fix: refactor ariaSortValue to useMemo, remove as const

78d8e33

Addresses PR review from markus101: nested ternary failed linting, replaced with useMemo block per suggested pattern. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Fix: use translate() for Advanced Settings aria-label in Table

523c341

Addresses PR review from markus101: hardcoded string replaced with translate('AdvancedSettings'); import added. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Fix: revert useUiSettings PATH to /settings/ui

ea9c5e3

The /config/ui path was incorrect; /settings/ui is consistent with all other settings hooks (general, mediamanagement, naming, etc.). Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

matalvernaz and others added 2 commits March 29, 2026 00:59

Fix: resolve all eslint/prettier linting errors

a9587f0

Auto-fix prettier formatting and import sort order across all files flagged by yarn lint. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

matalvernaz and others added 4 commits March 29, 2026 14:06

Fix crash on Wanted page when queue item has no episodeIds

7b3644a

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

CI: add GitHub Actions lint check on frontend push

26b16a9

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Remove lint steps from build.sh, now handled by GitHub Actions

cda097c

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Remove build.sh from repo, local dev script only

d45a3b5

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Remove CI workflow, upstream already handles linting

d0eb074

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

markus101 requested changes Apr 12, 2026

View reviewed changes

	<IconButton name={icons.INFO} aria-label="Details" onPress={handleDetailsPress} />
	<IconButton name={icons.INFO} aria-label={translate('Details')} onPress={handleDetailsPress} />

	<IconButton name={icons.ADD} aria-label="Add" onPress={handleAddPress} />
	<IconButton name={icons.ADD} aria-label={translate('Add')} onPress={handleAddPress} />

	<IconButton name={icons.ADVANCED_SETTINGS} aria-label="Advanced Settings" />
	<IconButton name={icons.ADVANCED_SETTINGS} aria-label={translate('AdvancedSettings')} />

Uh oh!

Conversation

matalvernaz commented Mar 26, 2026

What's fixed

Changes

Uh oh!

stevietv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matalvernaz commented Mar 27, 2026

Uh oh!

stevietv commented Mar 27, 2026

Uh oh!

matalvernaz commented Mar 27, 2026

Uh oh!

markus101 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matalvernaz commented Mar 29, 2026

Uh oh!

stevietv commented Mar 29, 2026

Uh oh!

matalvernaz commented Mar 29, 2026

Uh oh!

markus101 commented Mar 29, 2026

Uh oh!

matalvernaz commented Mar 29, 2026

Uh oh!

markus101 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matalvernaz Apr 15, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

matalvernaz Apr 15, 2026 •

edited

Loading