[QuncCccccc]

IconButton resolves its Material style variant from the closest IconButtonTheme only. An IconButtonTheme that doesn't set variant therefore resets its subtree to Material 3, even when an ancestor opted into Material 3 Expressive. ListTile, InputDecorator, and AppBar hit this too, because they wrap their children in an internal IconButtonTheme without a variant.

This PR makes a null IconButtonThemeData.variant inherit the variant of the enclosing icon button themes:

• Adds IconButtonTheme.variantOf, which returns the first non-null variant of the enclosing IconButtonThemes, and then falls back to ThemeData.iconButtonTheme.variant, and then to StyleVariant.material3. IconButton now uses it instead of IconButtonTheme.of(context).variant.
• Keeps the current behavior of style: the closest theme replaces its ancestors. An explicit variant: StyleVariant.material3 still opts a subtree out.
• Documents that an enclosing IconButtonTheme takes precedence over ThemeData.iconButtonTheme, and that IconButtonTheme.of only returns the variant specified by the closest theme.

Fixes flutter/flutter#194414

TODO:

• Follow-up PR:
  • AppBar, ListTile, and InputDecorator set variant: IconButtonTheme.variantOf(context) on the themes they create. This fixes the common cases above.
  • I'll also add some notes to the variant docs: dialogs, bottom sheets, and menus only get the closest theme, so set the variant in ThemeData or on that theme.
• Update the M3E migration checklist (the migration skill): a theme that a widget creates internally should always set variant, either to variantOf(context) or to StyleVariant.material3.

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. 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.

Footnotes

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. ↩ ↩²

[gemini-code-assist]

Code Review

This pull request introduces IconButtonTheme.variantOf, a static method that retrieves the closest non-null IconButtonThemeData.variant from the ancestor tree, falling back to ThemeData.iconButtonTheme.variant. IconButton is updated to use this new method for resolving its style variant. The changes also include updated documentation, a pending changelog entry, and comprehensive unit tests verifying the inheritance, precedence, and rebuilding behavior of the new method. There are no review comments, and I have no feedback to provide.

[dkwingsmt]

LGTM.

I'd like to point out that this method misses an edge case as described below. However, this edge case is unlikely to come up in typical cases and addressing it properly would require much broader discussion, so this PR is already a valuable improvement worth landing as-is. I will open an issue or RFC to discuss it.

---

The edge case is about InheritedTheme.capture, which used in showDialog, showModalBottomSheet, PopupMenuButton, etc. The capture only records the closest InheritedTheme of each runtimeType, if a route has an outer IconButtonTheme that sets variant and an inner IconButtonTheme with variant: null, capturing themes from inside the inner theme (e.g. via showDialog) will only capture the inner one and lose the outer variant in the new route.

  testWidgets('InheritedTheme.captureAll preserves the inherited variant', (
    WidgetTester tester,
  ) async {
    StyleVariant? capturedVariant;
    await tester.pumpWidget(
      MaterialApp(
        home: IconButtonTheme(
          data: const IconButtonThemeData(variant: StyleVariant.material3Expressive),
          child: IconButtonTheme(
            data: const IconButtonThemeData(
              style: ButtonStyle(foregroundColor: WidgetStatePropertyAll<Color>(Color(0xffff0000))),
            ),
            child: Builder(
              builder: (BuildContext context) {
                return ElevatedButton(
                  onPressed: () {
                    Navigator.of(context).push(
                      MaterialPageRoute<void>(
                        builder: (BuildContext routeContext) {
                          return InheritedTheme.captureAll(
                            context,
                            Builder(
                              builder: (BuildContext innerContext) {
                                capturedVariant = IconButtonTheme.variantOf(innerContext);
                                return const SizedBox();
                              },
                            ),
                          );
                        },
                      ),
                    );
                  },
                  child: const Text('Push'),
                );
              },
            ),
          ),
        ),
      ),
    );

    await tester.tap(find.text('Push'));
    await tester.pumpAndSettle();

    expect(capturedVariant, StyleVariant.material3Expressive);
  });

[QuncCccccc]

The capture only records the closest InheritedTheme of each runtimeType, if a route has an outer IconButtonTheme that sets variant and an inner IconButtonTheme with variant: null, capturing themes from inside the inner theme (e.g. via showDialog) will only capture the inner one and lose the outer variant in the new route.

It makes sense!

This can also happen without a custom nested theme. AppBar, ListTile, and InputDecorator wrap icon buttons in their own IconButtonTheme without a variant. So a dialog or menu opened from one of them loses the variant too, if M3E was turned on with an IconButtonTheme inside the page (for example, around MaterialApp.home). Turning it on through ThemeData isn't affected.

Before we fully solve this problem, I'll do the following (I'll also add these TODOs in PR description):

1. I'll land this PR as is.
2. Follow-up PR:
   • AppBar, ListTile, and InputDecorator set variant: IconButtonTheme.variantOf(context) on the themes they create. This fixes the common cases above.
   • I'll also add some notes to the variant docs: dialogs, bottom sheets, and menus only get the closest theme, so set the variant in ThemeData or on that theme.
3. Update the M3E migration checklist (the migration skill): a theme that a widget creates internally should always set variant, either to variantOf(context) or to StyleVariant.material3.

[dkwingsmt]

I've extracted the issue I posted above into flutter/flutter#196177 for better tracking.