Fix TextField accessibility - contentDescription was ignored by kdroidFilter · Pull Request #2680 · JetBrains/compose-multiplatform-core

kdroidFilter · 2026-01-13T07:53:56Z

Description

Fixes TextField accessibility issue on Desktop (macOS) where contentDescription provided via Modifier.semantics {} was completely ignored by VoiceOver screen readers. Before this fix, TextField components were unusable for screen reader users because the text content was used as both the accessible name (label) and value (content), making unlabeled fields indistinguishable.

The fix updates ComposeAccessible.getAccessibleName() to prioritize contentDescription as the accessible name for text fields, aligning the behavior with iOS accessibility standards.

Before

TextField(
    value = "john@example.com",
    modifier = Modifier.semantics {
        contentDescription = "Email" // ❌ Ignored
    }
)

VoiceOver: "john@example.com" (no label)

After

TextField(
    value = "john@example.com",
    modifier = Modifier.semantics {
        contentDescription = "Email" // ✅ Used as accessible name
    }
)

VoiceOver: "Email", "john@example.com" (label + value)

Visual comparison:

Before fix:

After fix:

Testing

Unit Tests:

Added tests in AccessibilityTest.kt covering:
- TextField with contentDescription → uses contentDescription as accessible name
- TextField without contentDescription → falls back to text content

Manual Testing:

Tested with VoiceOver on macOS
Verified TextField with and without contentDescription
Confirmed proper announcement of label and value

Release Notes

Fixes - Desktop

Fix TextField accessibility issue where contentDescription was ignored by screen readers (VoiceOver). TextField now properly uses contentDescription as the accessible name/label, making forms usable with assistive technologies.

Google CLA

Note: I have signed the Google Contributor's License Agreement at https://cla.developers.google.com

google-cla · 2026-01-13T07:54:01Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

m-sasha · 2026-01-13T10:40:42Z

+            if (setText != null) {
+                return semanticsConfig
+                    .getOrNull(SemanticsProperties.ContentDescription)
+                    ?.mergeText()
+                    ?: text?.toString()
+            }


Is there a reason we should not just always return

(semanticsConfig.getOrNull(SemanticsProperties.Text) ?: semanticsConfig.getOrNull(SemanticsProperties.ContentDescription)) ?.mergeText()

?

i.e., why only if setText != null?

The setText != null check is necessary because Text ?: ContentDescription doesn't work for the fallback case.

I tested your suggestion and it fails the textFieldAccessibleNameFallsBackToTextContent test. The issue is that for TextFields, SemanticsProperties.Text may exist in the config but doesn't provide the actual text content—that comes from the text field (via AccessibleText).

So when there's no contentDescription, we need text?.toString() as fallback, not SemanticsProperties.Text.

Err, sorry, I meant the other way around (ContentDescription ?: Text).

My point was that it seems to me the content description should be used (if set) not just for text fields (or editable text components in general).

I understand your point—using ContentDescription ?: Text for all components would be more consistent.

However, this fails the textFieldAccessibleNameFallsBackToTextContent test because SemanticsProperties.Text is null/empty for editable TextFields.

The fallback needs text?.toString() (from the Java AccessibleText API), not SemanticsProperties.Text (from Compose semantics). The setText != null check ensures we use the correct fallback source specifically for text fields.

My question wasn't about semanticsConfig.getOrNull(SemanticsProperties.Text) vs. text (which is just a calculated property of ComposeAccessibleComponent, by the way; it doesn't come from the Java API), although that's a valid question too. It was about using ContentDescription even if setText is null. Is there a reason not to do that?

About the question of semanticsConfig.getOrNull(SemanticsProperties.Text) vs. text (which itself is EditableText ?: Text): I don't think it's correct to use EditableText in getAccessibleName (or getAccessibleDescription.

So my suggestion is:

In getAccessibleName return ContentDescription ?: Text.

In getAccessibleDescription return ContentDescription.

Do you know of any cases where this would result in undesirable behavior from the OS accessibility system?

Hmm, getAccessibleDescription already returns ContentDescription.

So just the first suggestion then.

Ah, sorry, I hadn’t understood it properly.

On my side, I also didn’t fully understand why EditableText was being used in getAccessibleName, but I intentionally kept it to avoid introducing overly large changes. My goal was really to fix this specific bug, without further altering the existing behavior.

To my knowledge, this should not cause any issues with screen readers: they should be able to read the content correctly through the AccessibleText interface.

Would you like me to apply the proposed changes?

Would you like me to apply the proposed changes?

Yes, let's do that, and if/when anyone complains we'll fix it (and document exactly why).

I've implemented your suggestion.
However, when running all AccessibilityTest tests together, 10 tests fail with assert(activeControllers.isEmpty()) in the cleanup. These same tests pass when run individually.

m-sasha · 2026-01-14T19:15:46Z

Please format the PR summary according to https://raw.githubusercontent.com/JetBrains/compose-multiplatform-core/refs/heads/jb-main/.github/PULL_REQUEST_TEMPLATE.md

Also, if you haven't already, sign the Google Contributor's License Agreement at https://cla.developers.google.com to let us upstream your code to Google's AOSP repository

kdroidFilter · 2026-01-28T18:24:42Z

@MSasha I've reformatted the PR according to the template. The description, testing details, and release notes are now properly structured.

Regarding the Google CLA, I've signed it at https://cla.developers.google.com ✓

m-sasha · 2026-02-02T10:39:42Z

@kdroidFilter Please rebase on latest jb-main and apply this patch:

Subject: [PATCH] Moved a11y-related parts of ComposeSceneMediator.DesktopSemanticsOwnerManager into ComposeSceneAccessibility
---
Index: compose/ui/ui/src/desktopTest/kotlin/androidx/compose/ui/platform/AccessibilityTest.kt
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/compose/ui/ui/src/desktopTest/kotlin/androidx/compose/ui/platform/AccessibilityTest.kt b/compose/ui/ui/src/desktopTest/kotlin/androidx/compose/ui/platform/AccessibilityTest.kt
--- a/compose/ui/ui/src/desktopTest/kotlin/androidx/compose/ui/platform/AccessibilityTest.kt	(revision 349e958f6b83ded1856b44ee29fc2658453028d3)
+++ b/compose/ui/ui/src/desktopTest/kotlin/androidx/compose/ui/platform/AccessibilityTest.kt	(date 1770028677392)
@@ -630,7 +630,14 @@
         val deferredWindow = CompletableDeferred<ComposeWindow>()
         launchTestWindowApplication {
             val focusRequester = remember { FocusRequester() }
-            TextField(rememberTextFieldState("text"), Modifier.focusRequester(focusRequester))
+            TextField(
+                state = rememberTextFieldState("Hello, World"),
+                modifier = Modifier
+                    .focusRequester(focusRequester)
+                    .semantics {
+                        contentDescription = "text"
+                    }
+            )
             LaunchedEffect(Unit) { focusRequester.requestFocus() }
             LaunchedEffect(Unit) { deferredWindow.complete(this@launchTestWindowApplication.window) }
         }

kdroidFilter · 2026-02-02T18:12:29Z

@m-sasha I've rebased on the latest jb-main and applied the patch.

m-sasha · 2026-02-02T18:15:38Z

Thanks, running the CI tests now.

- Changed getAccessibleName() to prioritize contentDescription over text - Added tests for TextField with and without contentDescription - Applied patch to initiallyFocusedElementNotifiesSystemOfFocus test

kdroidFilter · 2026-02-02T19:12:39Z

@m-sasha I had an issue during the rebase - some deleted tests were reintroduced, which caused the CI to fail. I've fixed this now. Could you please restart the ci?

m-sasha · 2026-02-02T19:15:03Z

Running

kdroidFilter · 2026-02-02T19:39:40Z

@m-sasha
All checks are now passing :)

m-sasha reviewed Jan 13, 2026

View reviewed changes

m-sasha self-requested a review January 14, 2026 19:13

kdroidFilter force-pushed the textfield-accessible-name branch from 86c0a9e to 8c63496 Compare February 2, 2026 18:05

Fix TextField accessibility - use contentDescription as accessible name

eb896e9

- Changed getAccessibleName() to prioritize contentDescription over text - Added tests for TextField with and without contentDescription - Applied patch to initiallyFocusedElementNotifiesSystemOfFocus test

kdroidFilter force-pushed the textfield-accessible-name branch from 8c63496 to eb896e9 Compare February 2, 2026 19:09

m-sasha merged commit 98f13d1 into JetBrains:jb-main Feb 2, 2026
16 checks passed

Conversation

kdroidFilter commented Jan 13, 2026 • edited by svastven Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Before

After

Testing

Release Notes

Fixes - Desktop

Google CLA

Uh oh!

google-cla Bot commented Jan 13, 2026

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!

kdroidFilter Jan 13, 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!

Choose a reason for hiding this comment

Uh oh!

m-sasha commented Jan 14, 2026

Uh oh!

kdroidFilter commented Jan 28, 2026

Uh oh!

m-sasha commented Feb 2, 2026

Uh oh!

kdroidFilter commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

m-sasha commented Feb 2, 2026

Uh oh!

kdroidFilter commented Feb 2, 2026

Uh oh!

m-sasha commented Feb 2, 2026

Uh oh!

kdroidFilter commented Feb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kdroidFilter commented Jan 13, 2026 •

edited by svastven

Loading

kdroidFilter Jan 13, 2026 •

edited

Loading

kdroidFilter commented Feb 2, 2026 •

edited

Loading