Skip to content

Fix: Correct semantic binding issue#341

Merged
cedvdb merged 4 commits intocedvdb:mainfrom
WillCallahan:fix/semantics
Jan 2, 2026
Merged

Fix: Correct semantic binding issue#341
cedvdb merged 4 commits intocedvdb:mainfrom
WillCallahan:fix/semantics

Conversation

@WillCallahan
Copy link
Contributor

@WillCallahan WillCallahan commented Dec 23, 2025

This PR resolves a critical accessibility issue where the country selector button within PhoneFormField was inaccessible to screen reader users.

How to Reproduce the Error

The issue can be reproduced by enabling semantics in your app, for example, by adding the following lines to your main.dart:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SemanticsBinding.instance.ensureSemantics();
  runApp(const MyApp());
}

With semantics enabled, the country selector button was not focusable or interactive for screen readers.

The Fix

The problematic PhoneFieldSemantics widget has been removed. The CountryButton now provides its own correct semantic information (descriptive label, button role), allowing screen readers to interact with it properly.

Impact

Screen reader users can now correctly focus, understand, and activate the country selector.

Testing

To test this change:

  1. Enable a screen reader (e.g., VoiceOver/TalkBack).
  2. Navigate to a PhoneFormField.
  3. Verify the screen reader announces the country selector button descriptively (e.g., "United States +1, button").
  4. Verify the button can be activated via the screen reader's activation gesture.

Related Issues

Checklist

Supporting Documentation

This commit addresses accessibility issues in the PhoneFormField by ensuring the country selector button is properly exposed to accessibility services.

Previously:
- The PhoneFieldSemantics widget wrapped the entire PhoneFormField, using ExcludeSemantics to hide the internal components (including the country selector button) from the accessibility tree.
- The CountryButton itself lacked proper semantic labeling, making it difficult for screen readers to convey its purpose.

Changes Made:
- Removed the redundant PhoneFieldSemantics widget and its corresponding file (). The TextField now provides its own semantics, which is sufficient.
- Enhanced the CountryButton widget () by wrapping its content in a Semantics widget. This new Semantics widget provides a descriptive label including the current country's name and dial code, and marks it as a button, allowing screen readers to correctly identify and interact with it.
- Removed the import statement for  from .

Impact:
- Users relying on screen readers can now properly interact with and understand the purpose of the country selector button in the PhoneFormField, significantly improving accessibility.
@WillCallahan WillCallahan marked this pull request as draft December 23, 2025 16:00
@WillCallahan WillCallahan changed the title Improve accessibility of PhoneFormField Fix: Correct semantic binding issue Dec 23, 2025
@WillCallahan WillCallahan marked this pull request as ready for review December 23, 2025 16:59
@MahMoos
Copy link

MahMoos commented Dec 31, 2025

@cedvdb can we have this merged and released please?

@WillCallahan
Copy link
Contributor Author

I have made the required updates and tested this

@cedvdb cedvdb merged commit a0efb65 into cedvdb:main Jan 2, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Semantics not working

3 participants