iOS Setting SemanticFocus on ContentPage

Question

iOS Setting SemanticFocus on ContentPage

Bubba Jones 0

I am testing the voiceover function for iOS. For this I have a ContentPage which contains:

An AccessibilityTitle set to describe the page itself
AccessbilityText for every element within the page (these elements can be Labels, ContentViews etc

What I am trying to achieve is:

A: Upon navigating to the ContentPage should be focused and the AccessibilityTitle should be read.

B: What ACTUALLY occurs is that upon navigating to the ContentPage is that the first element WITHIN the page is automatically gets semantic focus. Thus THAT AccessibilityText is read out (instead of the title of the page).

In order to remedy the above I understand that I have to set the SemanticFocus to the ContentPage itself upon page loading thereby reading out the AccessibilityTitle of the page .

I used the the below in my ContentPageName.xaml.cs to avail. What happens is that the below gets ignored and the first element WITHIN the page automatically gets semantic focus.

    private void OnLoaded(object sender, EventArgs e)
    {
        _ = Task.Run(async () =>
        {            
			// this below is the ContentPage; note that I am waiting for the page to be //fully loaded as per this method
            this.SetSemanticFocus();        
        });
    }

Starry Night 30 Reputation points

2025-08-06T07:40:03.68+00:00

An AccessibilityTitle set to describe the page itself

I notice that SemanticProperties class of Maui doesn't have property AccessibilityTitle while iOS native has such instance Property accessibilityTitle. How do you set this property? Could you please post more code snippets so that we can test on our side?

2 answers

Your answer

Starry Night 30 Reputation points

2025-08-06T07:40:03.68+00:00

An AccessibilityTitle set to describe the page itself

I notice that SemanticProperties class of Maui doesn't have property AccessibilityTitle while iOS native has such instance Property accessibilityTitle. How do you set this property? Could you please post more code snippets so that we can test on our side?

Answer 1

Michael Le (WICLOUD CORPORATION) 1,145 Microsoft External Staff

Hello,

The method SetSemanticFocus() is being called from a background thread (Task.Run) and possibly before the UI is fully rendered. This prevents the semantic focus from being correctly applied to the ContentPage.

Recommended Solution:

I recommend you ensure SetSemanticFocus() is executed on the main UI thread and after the page has appeared. Use the MainThread.BeginInvokeOnMainThread method with a slight delay to allow the layout to complete.

And in the future, avoid using Task.Run for UI-related operations in .NET MAUI, as it can lead to threading issues.

Updated Code Example:

protected override void OnAppearing()
{
    base.OnAppearing();
   
    MainThread.BeginInvokeOnMainThread(async () =>
    {
        // Allow layout to complete - may need adjustment based on UI complexity
        await Task.Delay(100);
       
        try
        {
            this.SetSemanticFocus();
        }
        catch (Exception ex)
        {
            // Handle potential SetSemanticFocus inconsistencies
            System.Diagnostics.Debug.WriteLine($"SetSemanticFocus failed: {ex.Message}");
        }
    });
}

I hope this helps resolve the issue.

Reference:

Create a thread on the .NET MAUI UI thread

Bubba Jones 0

@Michael Le (WICLOUD CORPORATION)

Thank you for responding. While BeginInvokeOnMainThread was a good approach (since we are dealing with iOS) unfortunately this did not solve the problem. Basically no matter what value I put in the Task.Delay the code, while invoked, does not set focus on the ContentPage. I have tried 50, 150, 200 and 1000ms values for Task.Delay. No exception is thrown.

Note that I tried with OnAppearing but switched to OnLoaded is called after OnAppearing.

Below is my current code:

	public MainSettingsPage()
	{
		InitializeComponent();        
        Loaded += OnLoaded;
    }
    private void OnLoaded(object sender, EventArgs e)
    {        
        MainThread.BeginInvokeOnMainThread(async () =>
        {
            // used 50, 150, 200 and 1000
            await Task.Delay(1000);
            try
            {
				// This does not set the page to focus
                this.SetSemanticFocus();
            }
            catch (Exception ex)
            {
                // Handle potential SetSemanticFocus inconsistencies
                System.Diagnostics.Debug.WriteLine($"SetSemanticFocus failed: {ex.Message}");
            }
        });
    }

Bubba Jones 0

@Michael Le (WICLOUD CORPORATION) Thank you for responding. While BeginInvokeOnMainThread was a good approach (since we are dealing with iOS) unfortunately this did not solve the problem. Basically no matter what value I put in the Task.Delay the code, while invoked, does not set focus on the ContentPage. I have tried 50, 150, 200 and 1000ms values for Task.Delay. No exception is thrown. Note that I tried with OnAppearing but switched to OnLoaded is called after OnAppearing. Below is my current code:

	public MainSettingsPage()
	{
		InitializeComponent();        
        Loaded += OnLoaded;
    }
    private void OnLoaded(object sender, EventArgs e)
    {        
        MainThread.BeginInvokeOnMainThread(async () =>
        {
            // used 50, 150, 200 and 1000
            await Task.Delay(1000);
            try
            {
				// This does not set the page to focus
                this.SetSemanticFocus();
            }
            catch (Exception ex)
            {
                // Handle potential SetSemanticFocus inconsistencies
                System.Diagnostics.Debug.WriteLine($"SetSemanticFocus failed: {ex.Message}");
            }
        });
    }

Michael Le (WICLOUD CORPORATION) 1,145 Microsoft External Staff

I suppose there's an issue with setting focus on the ContentPage.

Since VoiceOver targets the first element on the page, have you tried creating a hidden label to act as a page title anchor as a workaround?

Place this before your first element in your XAML:

<!-- Hidden accessibility anchor for page title -->
<Label x:Name="PageTitleFocusAnchor"
       Text=""
       SemanticProperties.Description="Your Page Title - Brief description of what this page contains"
       IsVisible="False"
       HeightRequest="0"
       WidthRequest="0" />

Then in your code-behind, set focus to this hidden element:

protected override async void OnAppearing()
{
    base.OnAppearing();
   
    // Wait for layout completion
    await Task.Delay(200);
   
    // Set focus to our hidden page title anchor
    PageTitleFocusAnchor?.SetSemanticFocus();
}

Bubba Jones 0 Reputation points

2025-07-28T15:14:14.66+00:00

Thanks for the follow up response;

I have tried this approach before, unfortunately if the label is not visible OR HeightRequest and WidthRequest are set to 0 the Label does not respond to SetSemanticFocus.

In other words the user needs to be able to SEE the Label in order for SemanticFocus to work. Your above code works when I set the label to visible and set the height / width are non zero values.

Michael Le (WICLOUD CORPORATION) 1,145 Microsoft External Staff

Thanks for your sharing.

For curiosity, could you try these settings out and get back to me with the results?

<Label x:Name="PageTitleFocusAnchor"
        Text=""
        Opacity="0"
        IsVisible="True"
        SemanticProperties.Description="Your Page Title - Brief description of what this page contains"
        HeightRequest="1"
        WidthRequest="1" />

Michael Le (WICLOUD CORPORATION) 1,145 Reputation points Microsoft External Staff

2025-08-05T03:01:31.64+00:00

Let me know if you have any questions.
Bubba Jones 0 Reputation points

2025-08-07T08:23:21.57+00:00

Sorry for the late response. Your solution almost works because upon navigating to the Page, the text of the Label starts being read. However while its still being read, semantic focus is then re-diverted to the first other control in the page and that gets read instead.

In other words semantic focus still jumps to another control if I set the await to 100 ms. However if I modify the await to 1000 ms, upon navigating to the page, it reads out the first control of the page then after that it redirects to the label and that gets read out.

The ideal solution would be to disable semantic focus for every item in the page with the exception of the label, until the label is read, and then enable semantic focus for all items within the page.
Michael Le (WICLOUD CORPORATION) 1,145 Reputation points Microsoft External Staff

2025-08-07T09:09:22.0333333+00:00

Thank you for your time and sharing your experience.

Given that semantic focus behavior can be inconsistent in this scenario, it may be more effective to work with VoiceOver's natural behavior rather than attempting to override it. Consider implementing a properly visible and accessible label for the page title instead.

You could also explore iOS Accessibility Notifications as an alternative approach to integrate with VoiceOver more naturally, though this solution would require additional implementation effort.
Michael Le (WICLOUD CORPORATION) 1,145 Reputation points Microsoft External Staff

2025-08-12T03:10:09.74+00:00

Hello, I hope everything is working now. Let me know if you need further assistance.

Answer 2

This is a well-documented issue with VoiceOver focus behavior on iOS. One tweak that might help is ensuring SetSemanticFocus() runs on the main thread with a slight delay, as VoiceOver often requires the UI to be fully rendered before it respects focus changes. Wrapping the call in Device.BeginInvokeOnMainThread and adding a short Task.Delay (e.g., 100ms) can give the page enough time to settle before setting semantic focus to the ContentPage itself. This has proven effective in similar accessibility scenarios.

Share via

iOS Setting SemanticFocus on ContentPage

2 answers

Your answer