From eecb1d32f659f8becd8b27c97a72a820ba916bb6 Mon Sep 17 00:00:00 2001 From: David Ortinau Date: Sun, 7 Jun 2026 06:38:13 -0500 Subject: [PATCH 1/2] Document back button accessibility label in .NET MAUI 11 Adds documentation for the new accessibility-label APIs that flow SemanticProperties to the toolbar back button: - NavigationPage.BackButtonAccessibilityLabel attached property (new "Set the back button accessibility label" subsection in navigationpage.md, plus a NOTE in the property table). - BackButtonBehavior.AccessibilityLabel property (Shell, new moniker-gated block in shell/navigation.md's "Back button behavior" section). Both additions cross-link to docs/fundamentals/accessibility.md. Tracks dotnet/maui#35011 and aligns with the .NET 11 Preview 5 release notes published in dotnet/core#10433. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/fundamentals/shell/navigation.md | 21 +++++++++++++- docs/user-interface/pages/navigationpage.md | 31 ++++++++++++++++++++- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/shell/navigation.md b/docs/fundamentals/shell/navigation.md index 51b23b716e..c5ebf0c65b 100644 --- a/docs/fundamentals/shell/navigation.md +++ b/docs/fundamentals/shell/navigation.md @@ -1,7 +1,7 @@ --- title: ".NET MAUI Shell navigation" description: "Learn how .NET MAUI Shell apps can utilize a URI-based navigation experience that permits navigation to any page in the app, without having to follow a set navigation hierarchy." -ms.date: 01/14/2025 +ms.date: 06/05/2026 --- # .NET MAUI Shell navigation @@ -589,6 +589,25 @@ Back button appearance and behavior can be redefined by setting the also defines an `AccessibilityLabel` property of type `string`, which sets the accessibility label that screen readers announce for the back button. This is independent of `TextOverride`, so the visible label can stay short while the spoken label stays descriptive. The following example sets both properties together: + +```xaml + + + + + ... + +``` + +Setting an explicit `AccessibilityLabel` is recommended whenever `IconOverride` is set or `TextOverride` is hidden, because screen readers would otherwise announce a generic value or no value at all. For more accessibility guidance, see [Accessibility](~/fundamentals/accessibility.md). + +:::moniker-end + ::: moniker range="=net-maui-8.0" All of these properties are backed by objects, which means that the properties can be targets of data bindings. Each has a `OneTime` binding mode, which means that data goes from the source to the target but only when the `BindingContext` changes. diff --git a/docs/user-interface/pages/navigationpage.md b/docs/user-interface/pages/navigationpage.md index fcf15b6f1f..22d60271eb 100644 --- a/docs/user-interface/pages/navigationpage.md +++ b/docs/user-interface/pages/navigationpage.md @@ -1,7 +1,7 @@ --- title: "NavigationPage" description: "The .NET MAUI NavigationPage is used to perform hierarchical navigation through a stack of last-in, first-out (LIFO) pages." -ms.date: 11/28/2025 +ms.date: 06/05/2026 --- # NavigationPage @@ -24,6 +24,13 @@ The .NET Multi-platform App UI (.NET MAUI) , defines the icon that represents the title on the navigation bar. This is an attached property. - `TitleView`, of type , defines the view that can be displayed in the navigation bar. This is an attached property. +:::moniker range=">=net-maui-11.0" + +> [!NOTE] +> Starting in .NET MAUI 11, also defines a `BackButtonAccessibilityLabel` attached property of type `string`, which sets the accessibility label that screen readers announce for the back button on the navigation bar. See [Set the back button accessibility label](#set-the-back-button-accessibility-label) for an example. + +:::moniker-end + These properties are backed by objects, which means that they can be targets of data bindings, and styled. The class also defines three events: @@ -208,6 +215,28 @@ In this example, the current page is removed from the modal stack, with the new On Android, you can always return to the previous page by pressing the standard *Back* button on the device. If the modal page requires a self-contained task to be completed before leaving the page, the app must disable the *Back* button. This can be accomplished by overriding the `Page.OnBackButtonPressed` method on the modal page. +:::moniker range=">=net-maui-11.0" + +### Set the back button accessibility label + +Starting in .NET MAUI 11, you can set the accessibility label that screen readers (TalkBack on Android, VoiceOver on iOS and Mac Catalyst, Narrator on Windows) announce for the back button on a navigation bar. The label is set with the `NavigationPage.BackButtonAccessibilityLabel` attached property, which lives on the destination page—the page the back button returns *to* on the user's behalf: + +```xaml + + + +``` + +Setting an explicit label is recommended when the back button title is hidden, abbreviated, or shows only an icon, because screen readers would otherwise announce a generic value or no value at all. The label is independent of the `BackButtonTitle` attached property, so the visible title can stay short while the spoken label stays descriptive. + +For more accessibility guidance, see [Accessibility](~/fundamentals/accessibility.md). + +:::moniker-end + ## Page navigation events The class defines `NavigatedTo`, `NavigatingFrom`, and `NavigatedFrom` navigation events that are raised during page navigation. The `NavigatingFrom` event is raised when the current page is about to be navigated away from. The `NavigatedFrom` event is raised after the current page has been navigated away from. The `NavigatedTo` event is raised after navigating to the current page. From 1350465024c90d57bb36f35dd4c92f80df8d2282 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Fri, 12 Jun 2026 10:04:38 +0200 Subject: [PATCH 2/2] Apply back button accessibility review suggestions Use consistent DocFX moniker spacing and align the explanatory text with the XAML samples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/fundamentals/shell/navigation.md | 6 +++--- docs/user-interface/pages/navigationpage.md | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/shell/navigation.md b/docs/fundamentals/shell/navigation.md index c5ebf0c65b..5f20801d6a 100644 --- a/docs/fundamentals/shell/navigation.md +++ b/docs/fundamentals/shell/navigation.md @@ -589,9 +589,9 @@ Back button appearance and behavior can be redefined by setting the also defines an `AccessibilityLabel` property of type `string`, which sets the accessibility label that screen readers announce for the back button. This is independent of `TextOverride`, so the visible label can stay short while the spoken label stays descriptive. The following example sets both properties together: +Starting in .NET MAUI 11, also defines an `AccessibilityLabel` property of type `string`, which sets the accessibility label that screen readers announce for the back button. This is independent of `TextOverride`, so the visible label can stay short while the spoken label stays descriptive. The following example sets a custom icon and accessibility label together: ```xaml @@ -606,7 +606,7 @@ Starting in .NET MAUI 11, also Setting an explicit `AccessibilityLabel` is recommended whenever `IconOverride` is set or `TextOverride` is hidden, because screen readers would otherwise announce a generic value or no value at all. For more accessibility guidance, see [Accessibility](~/fundamentals/accessibility.md). -:::moniker-end +::: moniker-end ::: moniker range="=net-maui-8.0" diff --git a/docs/user-interface/pages/navigationpage.md b/docs/user-interface/pages/navigationpage.md index 22d60271eb..220c1daa1e 100644 --- a/docs/user-interface/pages/navigationpage.md +++ b/docs/user-interface/pages/navigationpage.md @@ -24,12 +24,12 @@ The .NET Multi-platform App UI (.NET MAUI) , defines the icon that represents the title on the navigation bar. This is an attached property. - `TitleView`, of type , defines the view that can be displayed in the navigation bar. This is an attached property. -:::moniker range=">=net-maui-11.0" +::: moniker range=">=net-maui-11.0" > [!NOTE] > Starting in .NET MAUI 11, also defines a `BackButtonAccessibilityLabel` attached property of type `string`, which sets the accessibility label that screen readers announce for the back button on the navigation bar. See [Set the back button accessibility label](#set-the-back-button-accessibility-label) for an example. -:::moniker-end +::: moniker-end These properties are backed by objects, which means that they can be targets of data bindings, and styled. @@ -215,11 +215,11 @@ In this example, the current page is removed from the modal stack, with the new On Android, you can always return to the previous page by pressing the standard *Back* button on the device. If the modal page requires a self-contained task to be completed before leaving the page, the app must disable the *Back* button. This can be accomplished by overriding the `Page.OnBackButtonPressed` method on the modal page. -:::moniker range=">=net-maui-11.0" +::: moniker range=">=net-maui-11.0" ### Set the back button accessibility label -Starting in .NET MAUI 11, you can set the accessibility label that screen readers (TalkBack on Android, VoiceOver on iOS and Mac Catalyst, Narrator on Windows) announce for the back button on a navigation bar. The label is set with the `NavigationPage.BackButtonAccessibilityLabel` attached property, which lives on the destination page—the page the back button returns *to* on the user's behalf: +Starting in .NET MAUI 11, you can set the accessibility label that screen readers (TalkBack on Android, VoiceOver on iOS and Mac Catalyst, Narrator on Windows) announce for the back button on a navigation bar. The label is set with the `NavigationPage.BackButtonAccessibilityLabel` attached property on the page whose navigation bar displays the back button: ```xaml