[Feedback Requested] Cross-platform Adaptation for Top App Bars (Navigation Bars)

[leighajarett]

What is a top app bar?

Top app bars display information and actions at the top of the screen. They can contain:

• A leading component, usually used to navigate between a hierarchy of content
• A title for the current screen
• An action, or a list of actions; usually buttons contextualize for the current screen

Platform differences

On the latest version of Android, app bars follow the design guidelines defined in Material 3. On iOS, an equivalent component is defined in Apple’s Human Interface Guidelines called navigation bars.

Both Material 3 and HIGs offer different designs depending on whether or not the user has scrolled on the page. For example, many iOS and Android system app bars display the text underneath the leading component when the user is positioned at the top of the page (see images below).

There are some notable differences on the design of the app bar between the two platforms, as shown in the table below. Note that Material colors referenced below a

	M3 Top App Bar	HIG Navigation Bar
Icons	Material Symbols, universal size is 48x48	SF Symbols, universal size is 44x44
Back Button Icon	arrow back	chevron backward
Button Colors	On surface	Accent color (default is systemBlue)
Platform Typography	Roboto regular	San Francisco regular (leading and actions) San Francisco bold (title)
Container Style	Color: Surface	Color: #EEEEEE, 100%
Container Color (on Scroll)	Color: Surface container	Color: Translucent. For developer guidance, see UIBlurEffect.Style Border: 1ps 0x4D000000
Container Height	Small: 64ps Medium: 112ps Large: 152ps	Small: 44ps Large: 117ps
Padding	Small: (8,4,8,4) Medium top: (8,4,0,4) Medium bottom: (0,16,20,16) Large top: (8,4,20,4) Large bottom: (40,16,20,16) Click here to see Material top app bar detailed padding specs	Small: (0,6,0,6) Large top: (0,6,0,6) Large bottom: (4,16,8,16)
Page Transitions	Material design uses the Android platform defaults for forward and backward navigation.	HIGs uses the iOS platform defaults for forward and backward navigation.
Other Animations	N/A	When the user selects the back button where the prior page name is displayed, there is an animation to bring the title below leading

The Flutter framework has four different widgets for displaying app bars:

• AppBar, which implements the specification defined by Material Design for simple app bars that keep an inline title while scrolling.
• SliverAppBar, which implements the specification defined by Material Design for app bars that move from a bottom title to an inline title while scrolling.
• CupertinoNavigationBar, which follows the look & feel of iOS bars with a title that stays inline.
• CupertinoSliverNavigationBar, which follows the look & feel of iOS bars that animate from a large title to an inline title while scrolling.

Adaptation recommendation

We recommend leveraging the platform-specific properties for the following:

• Icons
• Page transitions
• Font styling
• Container size
• Container styling

Rationale and exceptions

Matching iOS styling can help your Flutter app feel more natural to iOS users. However, it's important for your app bar to feel cohesive with the rest of your app. So, there are a few exceptions noted below:

• Adapt to iOS-style icons for system icons familiar to users (like the "back" or "more" ). Leverage custom icons for other buttons to help establish brand identity.
• Leverage iOS font families, styles and text alignment so long as its consistent with text styling throughout your app. For example, if you've chosen not to use bold text styles in other UI components, using iOS navigation bar's default styling may look out of place.

Example Code

Many Flutter apps leverage the existing Material AppBar widget or the SliverAppBar widget. These already supports the following automatic adaptations:

• BackButton: is used by default as the leading component. The icon adapts to the platform icon by default.
• Page transitions: navigation transitions on iOS and Android adapt by default in the Flutter framework.
• Font families: font families adapt by default in the Flutter framework.

However, you can further customize properties to match the iOS system as shown below:

Text styling

To match iOS styling, map the headlineMedium Material textTheme to the Cupertino navLargeTitleTextStyle textTheme:

TextTheme cupertinoTextTheme = TextTheme(
    headlineMedium: CupertinoThemeData()
        .textTheme
        .navLargeTitleTextStyle
         // fixes a small bug with spacing
        .copyWith(letterSpacing: -1.5),
    titleLarge: CupertinoThemeData().textTheme.navTitleTextStyle)
...

ThemeData(
      textTheme: Platform.isIOS ? cupertinoTextTheme : null,
      ...
)

App Bar

AppBar(
        surfaceTintColor: Platform.isIOS ? Colors.transparent : null,
        shadowColor: Platform.isIOS ? CupertinoColors.darkBackgroundGray : null,
        scrolledUnderElevation: Platform.isIOS ? .1 : null,
        toolbarHeight: Platform.isIOS ? 44 : null,
        title: Text(
          'My AppBar',
        ),
      ),
...

SliverAppBar

SliverAppBar.large(
          surfaceTintColor: Platform.isIOS ? Colors.transparent : null,
          toolbarHeight: Platform.isIOS ? 44 : kToolbarHeight,
          collapsedHeight: Platform.isIOS ? 44 : kToolbarHeight,
          expandedHeight: Platform.isIOS ? 117 : null,
          title: Text('My AppBar'),
          shadowColor: Platform.isIOS ? CupertinoColors.darkBackgroundGray : null,
          scrolledUnderElevation: Platform.isIOS ? .1 : null,
...

Automated Adaptation

Automated adaptation is not yet supported by Flutter for app bars. However, we are exploring ways to make this easier within the framework. If you’d like the Flutter team or community contributors to prioritize this feature, you can upvote flutter/flutter#124330 with a 👍emoji. If you have other ideas on how to make this experience more seamless, please add comments to this discussion.