[material_ui] Port flutter/flutter #185475 "Accessibility: Add semanticLabel to MenuAnchor" (#12806)
Ports flutter/flutter#185475 to `material_ui`, following the instructions in flutter/flutter#188444. The commits were cherry-picked from the original PR, with only file paths adjusted for this repo.
`MenuAnchor` had no way to label the expanded menu overlay, so screen readers announced nothing useful when a menu opened. This adds a `semanticLabel` property, applied to a `Semantics` node wrapping the submenu in `_buildOverlay`, and only when a label is provided.
The original PR also announced the label with `SemanticsService.announce` when the menu opened. Following @chunhtai's review feedback on flutter/flutter#185475, that part is dropped here: a semantics label should not double as announcement text, and anyone who wants an announcement can call `SemanticsService.announce` from `onOpen`. The last commit on this branch removes it.
## Tests
New test `MenuAnchor applies semanticLabel to the expanded menu overlay` in `packages/material_ui/test/menu_anchor_test.dart`, checking that the label is absent before the menu opens and present once it expands. The `menu_anchor.0` API example now sets a `semanticLabel`, and its example test still passes.
Fixes flutter/flutter#184876
Supersedes flutter/flutter#185475, which will be closed with a pointer to this PR.
## Pre-Review Checklist
**Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.
[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
diff --git a/packages/material_ui/example/lib/menu_anchor/menu_anchor.0.dart b/packages/material_ui/example/lib/menu_anchor/menu_anchor.0.dart
index a885f7e..b4973ef 100644
--- a/packages/material_ui/example/lib/menu_anchor/menu_anchor.0.dart
+++ b/packages/material_ui/example/lib/menu_anchor/menu_anchor.0.dart
@@ -112,6 +112,7 @@
children: <Widget>[
MenuAnchor(
animated: true,
+ semanticLabel: 'Cascading application menu',
onAnimationStatusChanged: (AnimationStatus status) {
// Store the animation status so that it can be used to determine
// whether the menu is opening or closing when the button is
diff --git a/packages/material_ui/lib/src/menu_anchor.dart b/packages/material_ui/lib/src/menu_anchor.dart
index bcc1a17..78d69aa 100644
--- a/packages/material_ui/lib/src/menu_anchor.dart
+++ b/packages/material_ui/lib/src/menu_anchor.dart
@@ -282,6 +282,7 @@
this.onAnimationStatusChanged,
required this.menuChildren,
this.builder,
+ this.semanticLabel,
this.child,
});
@@ -475,6 +476,11 @@
/// closed.
final MenuAnchorChildBuilder? builder;
+ /// The semantic label of the menu.
+ ///
+ /// Defaults to null.
+ final String? semanticLabel;
+
/// The optional child to be passed to the [builder].
///
/// Supply this child if there is a portion of the widget tree built in
@@ -714,6 +720,32 @@
}
Widget _buildOverlay(BuildContext context, RawMenuOverlayInfo position) {
+ Widget submenu = _Submenu(
+ fadeAnimation: opacityAnimation,
+ heightAnimation: heightAnimation,
+ layerLink: widget.layerLink,
+ consumeOutsideTaps: widget.consumeOutsideTap,
+ menuScopeNode: _menuScopeNode,
+ menuStyle: widget.style,
+ clipBehavior: widget.clipBehavior,
+ menuChildren: _menuChildren,
+ crossAxisUnconstrained: widget.crossAxisUnconstrained,
+ menuPosition: position,
+ anchor: this,
+ alignmentOffset: widget.alignmentOffset ?? Offset.zero,
+ reservedPadding: widget.reservedPadding ?? const EdgeInsets.all(_kMenuViewPadding),
+ );
+
+ // Only inject the semantics node if a label is provided
+ if (widget.semanticLabel != null) {
+ submenu = Semantics(
+ container: true,
+ explicitChildNodes: true,
+ label: widget.semanticLabel,
+ child: submenu,
+ );
+ }
+
// ExcludeSemantics, ExcludeFocus, and IgnorePointer are used to effectively
// disable all interactions with the menu while it is closing.
//
@@ -724,24 +756,7 @@
excluding: isClosingOrClosed,
child: IgnorePointer(
ignoring: isClosingOrClosed,
- child: ExcludeFocus(
- excluding: isClosingOrClosed,
- child: _Submenu(
- fadeAnimation: opacityAnimation,
- heightAnimation: heightAnimation,
- layerLink: widget.layerLink,
- consumeOutsideTaps: widget.consumeOutsideTap,
- menuScopeNode: _menuScopeNode,
- menuStyle: widget.style,
- clipBehavior: widget.clipBehavior,
- menuChildren: _menuChildren,
- crossAxisUnconstrained: widget.crossAxisUnconstrained,
- menuPosition: position,
- anchor: this,
- alignmentOffset: widget.alignmentOffset ?? Offset.zero,
- reservedPadding: widget.reservedPadding ?? const EdgeInsets.all(_kMenuViewPadding),
- ),
- ),
+ child: ExcludeFocus(excluding: isClosingOrClosed, child: submenu),
),
);
}
diff --git a/packages/material_ui/pending_changelogs/change_2026_09_09_1788954923085.yaml b/packages/material_ui/pending_changelogs/change_2026_09_09_1788954923085.yaml
new file mode 100644
index 0000000..d14725d
--- /dev/null
+++ b/packages/material_ui/pending_changelogs/change_2026_09_09_1788954923085.yaml
@@ -0,0 +1,3 @@
+changelog: |
+ - Adds a semanticLabel to MenuAnchor for the expanded menu overlay.
+version: minor
diff --git a/packages/material_ui/test/menu_anchor_test.dart b/packages/material_ui/test/menu_anchor_test.dart
index f541657..db9c3b4 100644
--- a/packages/material_ui/test/menu_anchor_test.dart
+++ b/packages/material_ui/test/menu_anchor_test.dart
@@ -7004,6 +7004,36 @@
await tester.pump();
expect(find.text('X'), findsOne);
});
+
+ testWidgets('MenuAnchor applies semanticLabel to the expanded menu overlay', (
+ WidgetTester tester,
+ ) async {
+ final SemanticsHandle handle = tester.ensureSemantics();
+ final controller = MenuController();
+
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Material(
+ child: Center(
+ child: MenuAnchor(
+ controller: controller,
+ semanticLabel: 'Custom Menu Label',
+ menuChildren: const <Widget>[Text('Menu Item')],
+ ),
+ ),
+ ),
+ ),
+ );
+
+ expect(find.bySemanticsLabel('Custom Menu Label'), findsNothing);
+
+ controller.open();
+ await tester.pumpAndSettle();
+
+ expect(find.bySemanticsLabel('Custom Menu Label'), findsOneWidget);
+
+ handle.dispose();
+ });
}
List<Widget> createTestMenus({
