[Top app bar] Incomplete Material 3 documentation

I’m currently trying out the new Material 3 features using com.google.android.material:material:1.5.0 and I’m pretty pleased with the results so far. Good job!

However there’s one thing that keeps bugging me in this process: The documentation is not easy to follow!

When browsing the Material 2 documentation on material.io on every page on the top the site wants me to check out Material 3. Once I click on the link and I’m redirected to me.material.io I get to the “correct”/up-to-date documentation, which is a lot shorter. Some parts even reference the “old” Material 2 documentation and it is not clear where Material 2 documentation still applies and where Material 3 superseded the previous recommendations. So I’ve been going back and forth a lotto try and figure out how the stuff works I need for my app.

There’s one particular thing I haven’t been able to find out though. If you look at the page for the “Top app bar” it proudly presents the differences between Material 2 and 3 where now the transition between the Status bar and the App bar is seamless and uses the same colour. Curiously a lot of example figures use this M3 design but sometimes just the M2 variant is shown without any explanation why it suddenly is the “old” version. The codelab guide for example doesn’t use M3-style status/app bar at all it’s always a 2 colored variant there. The Material Theme builder which is indirectly referenced by this guide does make use of this does use the M3-style.

By following the code examples in the documentation, I always get an app that has a different colour for the status bar (the primary colour) on a Virtual Android device with Android 12.

So I come to the conclusion that there must be one, or a combination of the following problems:

1. The documentation is incomplete and doesn’t contain the required piece of information to make this happen
2. There is an error on my side and I missed an (obvious) step and/or the docmentation is poorly structured for this particular topic
3. MCA doesn’t support this feature yet (even though the documentation suggests otherwise)

I’d be happy if you could help me complete the puzzle, most likely there is some sort of communication error somewhere, leading to the disconnect.

[dsn5ft]

I’m confused why android:fitsSystemWindows=“true” is never mentioned as XML property to fix insets it’s pretty convenient in most cases.

That’s a good point, I’m not sure why. But luckily I did mention it in my update to our doc (https://github.com/material-components/material-components-android/commit/b8e1f978940c218502ee6161d0b3f673299eceb0).

And your takeaways are correct. Re: your 3., yes it’s up to each View to decide whether it will add an inset listener and handle window insets by default. Most Material Views that touch the edges of the screen will automatically do that and add the extra padding - I think FABs are tough because they don’t have to be placed at the edge of a screen, so it’s less straightforward.

[RoiEXLab]

@dsn5ft

and the seamless effect is usually achieved by following the standard, app-wide Edge to Edge guidance (transparent status bar + window inset handling).

Thank you for the reply. The default edge-to-edge guide cleared a couple of things up for me and the things that weren’t immediately clear (like the question why app:liftOnScroll="true" didn’t work immediately) were cleared up after trying a couple of things. I’m confused why android:fitsSystemWindows="true" is never mentioned as XML property to fix insets it’s pretty convenient in most cases. (Also for some reason it didn’t work for com.google.android.material.floatingactionbutton.FloatingActionButton, not sure if that’s a bug and if it should be reported, but wrapping the whole thing inside another layout was a good enough workaround.)

So the key takeaways for me were:

1. The window needs WindowCompat.setDecorFitsSystemWindows(getWindow(), false);
2. The com.google.android.material.appbar.AppBarLayout needs android:fitsSystemWindows="true" so the lift-on-scroll mechanism works properly, the inner com.google.android.material.appbar.MaterialToolbar cannot have it otherwise it breaks
   • I previously had the problem the the surrounding CoordinatorLayout would fill the space above the app bar, displaying the wrong colour whenever you started to scroll.
3. You have to care about the insets on your own. layout_behaviour of the RecyclerView doesn’t automatically fix the bottom padding for you in this case (even though the inset of the AppBar is correctly considered)

So thank you for your time and I’m looking forward to a clearer documentation. Keep up the good work