DEV/material-components_material-components-android

mirror of https://github.com/material-components/material-components-android.git synced 2026-01-09 07:11:07 +08:00

Material Design Team 2f3d4f9efe [Docs] Updated the nomenclature of images and removed unused images.

PiperOrigin-RevId: 791194140

2025-08-08 17:46:44 +00:00

49 KiB

Raw Permalink Blame History

Top app bars (App bars)

App bars are placed at the top of the screen to help people navigate through a product. There are four variants of app bars.

Note: The top app bar component is renamed to app bar in the design language.

Search app bar
Small
Medium flexible
Large flexible

For implementation purposes, the search and small app bars can be grouped into regular top app bars, while the medium flexible and large flexible app bars can be grouped into collapsing top app bars.

An app bar can transform into a contextual action bar, remaining active until an action is taken or it is dismissed. For more information, see contextual action bar.

Note: Images use various dynamic color schemes.

Deprecated app bars

There are two variants that are being deprecated and are no longer recommended:

Medium - Replace with medium flexible.
Large - Replace with large flexible.

Medium
Large

Design & API documentation

Anatomy

Container
Leading button
Trailing elements
Headline
Subtitle

More details on anatomy items in the component guidelines.

M3 Expressive

M3 Expressive update

Before you can use Material3Expressive component styles, follow the Material3Expressive themes setup instructions.

The new search app bar supports icons inside and outside the search bar, and centered text. It opens the search view component when selected.

The new medium flexible and large flexible app bars come with significant improvements, and should replace medium and large app bars, which are being deprecated. The small app bar is updated with the same flexible improvements. More on M3 Expressive

Types and naming:

Renamed component from top app bar to app bar
Added search app bar
Deprecating medium and large app bars
Added medium flexible and large flexible app bars with:
- Reduced overall height
- Larger title text
- Subtitle
- Left- and center-aligned text options
- Text wrapping
- More flexible elements for imagery and filled buttons
Added features to small app bar:
- Subtitle
- Center-aligned text option
- More flexible elements for imagery and filled buttons

Key properties

Container attributes

Element	Attribute	Related method(s)	Default value
Color	`android:background`	`setBackground` `getBackground`	`?attr/colorSurface`
`MaterialToolbar` elevation	`android:elevation`	`setElevation` `getElevation`	`4dp`
`AppBarLayout` elevation	`android:stateListAnimator`	`setStateListAnimator` `getStateListAnimator`	`0dp` to `4dp` (see all states)

Element	Attribute	Related method(s)	Default value
`MaterialToolbar` icon	`app:navigationIcon`	`setNavigationIcon` `getNavigationIcon`	`null`
`MaterialToolbar` icon color	`app:navigationIconTint`	`setNavigationIconTint`	`?attr/colorOnSurface`

Title attributes

Element	Attribute	Related method(s)	Default value
`MaterialToolbar` title text	`app:title`	`setTitle` `getTitle`	`null`
`MaterialToolbar` subtitle text	`app:subtitle`	`setSubtitle` `getSubtitle`	`null`
`MaterialToolbar` title color	`app:titleTextColor`	`setTitleTextColor`	`?attr/colorOnSurface`
`MaterialToolbar` subtitle color	`app:subtitleTextColor`	`setSubtitleTextColor`	`?attr/colorOnSurfaceVariant`
`MaterialToolbar` title typography	`app:titleTextAppearance`	`setTitleTextAppearance`	`?attr/textAppearanceTitleLarge`
`MaterialToolbar` subtitle typography	`app:subtitleTextAppearance`	`setSubtitleTextAppearance`	`?attr/textAppearanceTitleMedium`
`MaterialToolbar` title centering	`app:titleCentered`	`setTitleCentered`	`false`
`MaterialToolbar` subtitle centering	`app:subtitleCentered`	`setSubtitleCentered`	`false`
`CollapsingToolbarLayout` collapsed title typography	`app:collapsedTitleTextAppearance`	`setCollapsedTitleTextAppearance`	`?attr/textAppearanceTitleLarge`
`CollapsingToolbarLayout` expanded title typography	`app:expandedTitleTextAppearance`	`setExpandedTitleTextAppearance`	`?attr/textAppearanceHeadlineSmall` for Medium `?attr/textAppearanceHeadlineMedium` for Large
`CollapsingToolbarLayout` collapsed title color	`android:textColor` (in `app:collapsedTitleTextAppearance`) or `app:collapsedTitleTextColor`	`setCollapsedTitleTextColor`	`?attr/colorOnSurface`
`CollapsingToolbarLayout` expanded title color	`android:textColor` (in `app:expandedTitleTextAppearance`) or `app:expandedTitleTextColor`	`setExpandedTitleTextColor`	`?attr/colorOnSurface`
`CollapsingToolbarLayout` collapsed subtitle typography	`app:collapsedSubtitleTextAppearance`	`setCollapsedSubtitleTextAppearance`	`?attr/textAppearanceTitleMedium`
`CollapsingToolbarLayout` expanded subtitle typography	`app:expandedSubtitleTextAppearance`	`setExpandedSubtitleTextAppearance`	`?attr/textAppearanceTitleLarge` for Medium `?attr/textAppearanceHeadlineSmall` for Large
`CollapsingToolbarLayout` collapsed subtitle color	`android:textColor` (in `app:collapsedSubtitleTextAppearance`) or `app:collapsedSubtitleTextColor`	`setCollapsedSubtitleTextColor`	`?attr/colorOnSurface`
`CollapsingToolbarLayout` expanded subtitle color	`android:textColor` (in `app:expandedSubtitleTextAppearance`) or `app:expandedSubtitleTextColor`	`setExpandedSubtitleTextColor`	`?attr/colorOnSurface`
`CollapsingToolbarLayout` expanded title margins	`app:expandedTitleMargin*`	`setExpandedTitleMargin*`	`16dp`
`CollapsingToolbarLayout` padding between expanded title and subtitle	`app:expandedTitlePadding`	`setExpandedTitlePadding`	`0dp`
`CollapsingToolbarLayout` title max lines	`app:maxLines`	`setMaxLines` `getMaxLines`	`1`
`CollapsingToolbarLayout` title ellipsize	`app:titleTextEllipsize`	`setTitleEllipsize` `getTitleEllipsize`	`end`
`CollapsingToolbarLayout` collapsed title gravity	`app:collapsedTitleGravity`	`setCollapsedTitleGravity` `getCollapsedTitleGravity`	`start\|center_vertical`
`CollapsingToolbarLayout` collapsed title gravity mode	`app:collapsedTitleGravityMode`	--	`availableSpace`
`CollapsingToolbarLayout` expanded title gravity	`app:expandedTitleGravity`	`setExpandedTitleGravity` `getExpandedTitleGravity`	`start\|bottom`

Action items attributes

Element	Attribute	Related method(s)	Default value
`MaterialToolbar` menu	`app:menu`	`inflateMenu` `getMenu`	`null`
`MaterialToolbar` icon color	N/A	N/A	`?attr/colorOnSurfaceVariant`

Element	Attribute	Related method(s)	Default value
`MaterialToolbar` icon	`android:src` and `app:srcCompat` in `actionOverflowButtonStyle` (in app theme)	`setOverflowIcon` `getOverflowIcon`	`@drawable/abc_ic_menu_overflow_material` (before API 23) or `@drawable/ic_menu_moreoverflow_material` (after API 23)
`MaterialToolbar` overflow theme	`app:popupTheme`	`setPopupTheme` `getPopupTheme`	`@style/ThemeOverlay.Material3.*`
`MaterialToolbar` overflow item typography	`textAppearanceSmallPopupMenu` and `textAppearanceLargePopupMenu` in `app:popupTheme` or app theme	N/A	`?attr/textAppearanceBodyLarge`

Scrolling behavior attributes

Element	Attribute	Related method(s)	Default value
`MaterialToolbar` or `CollapsingToolbarLayout` scroll flags	`app:layout_scrollFlags`	`setScrollFlags` `getScrollFlags` (on `AppBarLayout.LayoutParams`)	`noScroll`
`MaterialToolbar` collapse mode	`app:collapseMode`	`setCollapseMode` `getCollapseMode` (on `CollapsingToolbar`)	`none`
`CollapsingToolbarLayout` content scrim color	`app:contentScrim`	`setContentScrim` `setContentScrimColor` `setContentScrimResource` `getContentScrim`	`null`
`CollapsingToolbarLayout` status bar scrim color	`app:statusBarScrim`	`setStatusBarScrim` `setStatusBarScrimColor` `setStatusBarScrimResource` `getStatusBarScrim`	`@empty`
`CollapsingToolbarLayout` scrim animation duration	`app:scrimAnimationDuration`	`setScrimAnimationDuration` `getScrimAnimationDuration`	`600`
`CollapsingToolbarLayout` collapsing animation interpolator	`app:titlePositionInterpolator`	`setTitlePositionInterpolator`	`@null`
`AppBarLayout` lift on scroll	`app:liftOnScroll`	`setLiftOnScroll` `isLiftOnScroll`	`true`
`AppBarLayout` lift on scroll color	`app:liftOnScrollColor`	N/A	`?attr/colorSurfaceContainer`
`AppBarLayout` lift on scroll target view	`app:liftOnScrollTargetViewId`	`setLiftOnScrollTargetViewId` `getLiftOnScrollTargetViewId`	`@null`
`AppBarLayout` scroll effect	`app:layout_scrollEffect`	`setScrollEffect` `getScrollEffect`	`none`

`AppBarLayout` styles

Element	Style	Theme attribute
**Surface	`Widget.Material3.AppBarLayout`	`?attr/appBarLayoutStyle`

: background : : :: color style** : : :

`MaterialToolbar` styles

Element	Style	Theme attribute
Default style	`Widget.Material3.Toolbar`	`?attr/toolbarStyle`
Surface background color style	`Widget.Material3.Toolbar.Surface`	`?attr/toolbarSurfaceStyle`
On Surface color style	`Widget.Material3.Toolbar.OnSurface`	N/A

`CollapsingToolbarLayout` styles

Element	Style	Theme attribute
Default style	`Widget.Material3.CollapsingToolbar`	`?attr/collapsingToolbarLayoutStyle`
Medium style	`Widget.Material3.CollapsingToolbar.Medium`	`?attr/collapsingToolbarLayoutMediumStyle`
Large style	`Widget.Material3.CollapsingToolbar.Large`	`?attr/collapsingToolbarLayoutLargeStyle`

For the full list, see styles and attrs.

Variants of app bars

Search app bar

Use a search app bar to provide an emphasized entry-point to open the search view. Use it on home pages when search is key to the product.

Search app bars have a search field instead of heading text

Small app bar

Use in dense layouts or when a page is scrolled.

The following example shows a small top app bar with a page title, a navigation icon, two actions, and an overflow menu.

Small top app bar with light purple background, grey icons, and page title.

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.google.android.material.appbar.AppBarLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

        <com.google.android.material.appbar.MaterialToolbar
            android:id="@+id/topAppBar"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:minHeight="?attr/actionBarSize"
            app:title="@string/page_title"
            app:menu="@menu/top_app_bar"
            app:navigationIcon="@drawable/ic_close_24dp" />

    </com.google.android.material.appbar.AppBarLayout>

    <!-- Note: A RecyclerView can also be used -->
    <androidx.core.widget.NestedScrollView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_behavior="@string/appbar_scrolling_view_behavior">

        <!-- Scrollable content -->

    </androidx.core.widget.NestedScrollView>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

Note: In order to allow your top app bar to grow taller when the system font setting increases, you can use android:layout_height="wrap_content" + android:minHeight="?attr/actionBarSize" on your MaterialToolbar, as shown in the example above.

In @menu/top_app_bar.xml:

<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <item
        android:id="@+id/edit"
        android:title="@string/edit"
        android:contentDescription="@string/content_description_search"
        app:showAsAction="ifRoom" />

    <item
        android:id="@+id/favorite"
        android:icon="@drawable/ic_favorite_24dp"
        android:title="@string/favorite"
        android:contentDescription="@string/content_description_favorite"
        app:showAsAction="ifRoom" />

    <item
        android:id="@+id/more"
        android:title="@string/more"
        android:contentDescription="@string/content_description_more"
        app:showAsAction="never" />

</menu>

In menu/navigation icon drawables:

<vector
    ...
    android:tint="?attr/colorControlNormal">
    ...
</vector>

In code:

topAppBar.setNavigationOnClickListener {
    // Handle navigation icon press
}

topAppBar.setOnMenuItemClickListener { menuItem ->
    when (menuItem.itemId) {
        R.id.edit -> {
            // Handle edit text press
            true
        }
        R.id.favorite -> {
            // Handle favorite icon press
            true
        }
        R.id.more -> {
            // Handle more item (inside overflow menu) press
            true
        }
        else -> false
    }
}

Note: The above example is the recommended approach and, in order for it to work, you need to use a Theme.Material3.* theme containing the NoActionBar segment, such as the Theme.Material3.Light.NoActionBar. If not, an action bar will be added to the current Activity window. The MaterialToolbar can be set as the support action bar and thus receive various Activity callbacks, as shown in this guide.

Medium flexible app bar

Use to display a larger headline. It can collapse into a small app bar on scroll.

The medium flexible top app bar introduced in expressive updates includes flexible heights, multi-line support, and can contain a wider variety of elements. These features are already supported/configurable within the existing Medium variant. Therefore, the name of the existing medium variant will be reused in the Material3Expressive theme.

If you are using a Material3Expressive theme:

The existing ?attr/collapsingToolbarLayoutMediumStyle attribute has been updated to the new flexible behavior. You do not need to change your XML layouts to get the new functionality.

If you are not using a Material3Expressive theme:

You should migrate to one of the expressive themes to use the new flexible app bar styles.

To properly draw the subtitle in expanded mode. Please use the following:

  <com.google.android.material.appbar.AppBarLayout
      android:id="@+id/appbarlayout"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:fitsSystemWindows="true">

    <com.google.android.material.appbar.CollapsingToolbarLayout
        style="?attr/collapsingToolbarLayoutMediumStyle"
        android:id="@+id/collapsingtoolbarlayout"
        android:layout_width="match_parent"
        android:layout_height="?attr/collapsingToolbarLayoutMediumSize"
        app:layout_scrollFlags="scroll|exitUntilCollapsed|snap"
        app:expandedTitleGravity="bottom|center_horizontal">

      <com.google.android.material.appbar.MaterialToolbar
          android:id="@+id/toolbar"
          style="?attr/catalogToolbarWithCloseButtonStyle"
          android:layout_width="match_parent"
          android:layout_height="?attr/actionBarSize"
          android:elevation="0dp"
          app:layout_collapseMode="pin"
          app:title="Medium Title"
          app:subtitle="Medium Subtitle"/>
    </com.google.android.material.appbar.CollapsingToolbarLayout>
  </com.google.android.material.appbar.AppBarLayout>

Large flexible app bar

Use to emphasize the headline of the page.

The large flexible top app bar introduced in expressive updates includes flexible heights, multi-line support, and can contain a wider variety of elements. These features are already supported/configurable within the existing Large variant. Therefore, the name of the existing large variant will be reused in the Material3Expressive theme.

If you are using a Material3Expressive theme:

The existing ?attr/collapsingToolbarLayoutLargeStyle attribute has been updated to the new flexible behavior. You do not need to change your XML layouts to get the new functionality.

If you are not using a Material3Expressive theme:

You should migrate to one of the expressive themes to use the new flexible app bar styles.

To properly draw the subtitle in expanded mode. Please use the following:

  <com.google.android.material.appbar.AppBarLayout
      android:id="@+id/appbarlayout"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:fitsSystemWindows="true">

    <com.google.android.material.appbar.CollapsingToolbarLayout
        style="?attr/collapsingToolbarLayoutLargeStyle"
        android:id="@+id/collapsingtoolbarlayout"
        android:layout_width="match_parent"
        android:layout_height="?attr/collapsingToolbarLayoutLargeSize"
        app:layout_scrollFlags="scroll|exitUntilCollapsed|snap"
        app:expandedTitleGravity="bottom|center_horizontal">

      <com.google.android.material.appbar.MaterialToolbar
          android:id="@+id/toolbar"
          style="?attr/catalogToolbarWithCloseButtonStyle"
          android:layout_width="match_parent"
          android:layout_height="?attr/actionBarSize"
          android:elevation="0dp"
          app:layout_collapseMode="pin"
          app:title="Large Title"
          app:subtitle="Large Subtitle"/>
    </com.google.android.material.appbar.CollapsingToolbarLayout>
  </com.google.android.material.appbar.AppBarLayout>

Code implementation

Before you can use Material top app bars, you need to add a dependency to the Material components for Android library. For more information, go to the Getting started page.

Center aligning app bars

The guidance and code for the all the app bars are also applicable for center aligning the title in the app bars. To center align them, you only need to set the app:titleCentered and/or app:subtitleCentered attributes to true on your MaterialToolbar.

Center aligned top app bar with light purple background, grey icons, and page title.

Adding image to collapsing app bars

A collapsing top app bar with an image background, a page title, a navigation icon, two action icons, and an overflow menu:

App bar with image background and white icons. The page title is on a new line below the icons

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...
    android:fitsSystemWindows="true">

    <com.google.android.material.appbar.AppBarLayout
        ...
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:fitsSystemWindows="true">

        <com.google.android.material.appbar.CollapsingToolbarLayout
            style="?attr/collapsingToolbarLayoutLargeStyle"
            android:layout_width="match_parent"
            android:layout_height="?attr/collapsingToolbarLayoutLargeSize">

            <ImageView
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:src="@drawable/media"
                android:scaleType="centerCrop"
                android:fitsSystemWindows="true"
                android:contentDescription="@string/content_description_media" />

            <com.google.android.material.appbar.MaterialToolbar
                android:layout_width="match_parent"
                android:layout_height="?attr/actionBarSize"
                ...
                android:background="@android:color/transparent" />

        </com.google.android.material.appbar.CollapsingToolbarLayout>

    </com.google.android.material.appbar.AppBarLayout>

    ...

</androidx.coordinatorlayout.widget.CoordinatorLayout>

In res/values/themes.xml:

<style name="Theme.App" parent="Theme.Material3.*.NoActionBar">
    <item name="android:windowTranslucentStatus">true</item>
</style>

Adding filled trailing icon button to app bars

With Expressive updates, a filled trailing icon button can replace the default action items. To achieve this, please use the follow layout configuration.


  <com.google.android.material.appbar.AppBarLayout
      android:id="@+id/appbarlayout"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:fitsSystemWindows="true">

    <com.google.android.material.appbar.CollapsingToolbarLayout
        style="?attr/collapsingToolbarLayoutMediumStyle"
        android:id="@+id/collapsingtoolbarlayout"
        android:layout_width="match_parent"
        android:layout_height="?attr/collapsingToolbarLayoutMediumSize"
        app:layout_scrollFlags="scroll|exitUntilCollapsed|snap"
        app:toolbarId="@id/toolbar">
      <LinearLayout
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:orientation="horizontal"
          app:layout_collapseMode="pin">
        <com.google.android.material.appbar.MaterialToolbar
            android:id="@+id/toolbar"
            style="?attr/catalogToolbarWithCloseButtonStyle"
            android:layout_width="0dp"
            android:layout_height="?attr/actionBarSize"
            android:layout_weight="1"
            android:elevation="0dp"
            app:title="Medium Title"/>
        <Button
            android:id="@+id/action_button"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginEnd="8dp"
            android:layout_gravity="center_vertical"
            app:icon="@drawable/ic_star_checkable_24"/>
      </LinearLayout>
    </com.google.android.material.appbar.CollapsingToolbarLayout>
  </com.google.android.material.appbar.AppBarLayout>

Adding a circle to the navigation button

If you would like to add a circle background to the navigation icon, set the android:theme="@style/ThemeOverlay.Material3.Toolbar.CircleNavigationButton" theme overlay on your Toolbar or MaterialToolbar.

By default, the theme overlay above uses ?attr/colorSurfaceContainer for the circle color. This can be customized by extending the theme overlay and setting the toolbarNavigationButtonCircleColor attribute.

Applying scrolling behavior to app bars

When scrolling up, the collapsing top app bar transforms into a regular top app bar.

The following example shows the top app bar positioned at the same elevation as content. Upon scroll, it increases elevation and lets content scroll behind it.

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...>

    <com.google.android.material.appbar.AppBarLayout
        ...
        app:liftOnScroll="true">

        <com.google.android.material.appbar.MaterialToolbar
            ...
            />

    </com.google.android.material.appbar.AppBarLayout>

    ...

</androidx.coordinatorlayout.widget.CoordinatorLayout>

Note: If your scrolling view (RecyclerView, ListView, etc.) is nested within another view (e.g., a SwipeRefreshLayout), you should make sure to set app:liftOnScrollTargetViewId on your AppBarLayout to the id of the scrolling view. This will ensure that the AppBarLayout is using the right view to determine whether it should lift or not, and it will help avoid flicker issues.

The following example shows the top app bar disappearing upon scrolling up, and appearing upon scrolling down.

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...>

    <com.google.android.material.appbar.AppBarLayout
        ...>

        <com.google.android.material.appbar.MaterialToolbar
            ...
            app:layout_scrollFlags="scroll|enterAlways|snap"
            />

    </com.google.android.material.appbar.AppBarLayout>

    ...

</androidx.coordinatorlayout.widget.CoordinatorLayout>

Optionally, you can change the style in which the app bar disappears and appears when scrolling by setting a scroll effect. By default, a scroll effect of none is set which translates the app bar in-step with the scrolling content. The following option shows setting the compress scroll effect which clips the top app bar until it meets the top of the screen:

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...>

    <com.google.android.material.appbar.AppBarLayout
        ...>

        <com.google.android.material.appbar.MaterialToolbar
            ...
            app:layout_scrollFlags="scroll|enterAlways|snap"
            app:layout_scrollEffect="compress"
            />

    </com.google.android.material.appbar.AppBarLayout>

    ...

</androidx.coordinatorlayout.widget.CoordinatorLayout>

Making app bars accessible

Android's top app bar component APIs provide support for the navigation icon, action items, overflow menu and more, to inform the user what each action performs. While optional, their use is strongly encouraged.

Content descriptions

When using icons for navigation, action items and other elements of top app bars, you should set a content description for them so that screen readers like TalkBack are able to announce their purpose or action.

For an overall content description of the top app bar, set an android:contentDescription or use the setContentDescription method on the MaterialToolbar.

For the navigation icon, this can be achieved via the app:navigationContentDescription attribute or setNavigationContentDescription method.

For action items and items within the overflow menu, the content description needs to be set in the menu:

<menu ...>
    ...
    <item
          ...
          android:contentDescription="@string/content_description_one" />
    <item
          ...
          android:contentDescription="@string/content_description_two" />
</menu>

For images within collapsing top app bars, set an android:contentDescription or use the setContentDescription method for the ImageView.

Status bar and edge-to-edge

Small top app bar with edge-to-edge status bar.

A common configuration for modern top app bars, as seen above, is to have a seamless color shared with the status bar. The best way to achieve this is to follow the edge-to-edge guidance, which will result in a transparent status bar that lets the background color of the top app bar show through.

Make sure to set android:fitsSystemWindows="true" on your AppBarLayout (or MaterialToolbar if not using AppBarLayout), so that an extra inset is added to avoid overlap with the status bar.

If your AppBarLayout scrolls and content is visible under the status bar, you can set the AppBarLayout's statusBarForeground to a MaterialShapeDrawable to let AppBarLayout automatically match the status bar color to its own background.

In code:

appBarLayout.statusBarForeground =
    MaterialShapeDrawable.createWithElevationOverlay(context)

Or if using tonal surface colors instead of elevation overlays, you can simply set the statusBarForeground to colorSurface to let AppBarLayout automatically match the status bar color to its own background:

appBarLayout.setStatusBarForegroundColor(
    MaterialColors.getColor(appBarLayout, R.attr.colorSurface))

Customizing app bars

Theming app bars

App bars support the customization of color, typography, and shape.

App bar theming example

API and source code:

CoordinatorLayout
- Class definition
AppBarLayout
- Class definition
- Class source
MaterialToolbar
- Class definition
- Class source
CollapsingToolbarLayout
- Class definition
- Class source

A regular top app bar with Material theming:

Implementing app bar theming

Use theme attributes in res/values/styles.xml, which applies to all top app bars and affects other components:

<style name="Theme.App" parent="Theme.Material3.*.NoActionBar">
    ...
    <item name="colorSurface">@color/shrine_pink_100</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="android:statusBarColor">?attr/colorPrimary</item>
    <item name="android:windowLightStatusBar" tools:targetApi="m">true</item>
    <item name="textAppearanceTitleLarge">@style/TextAppearance.App.TitleLarge</item>
    <item name="textAppearanceTitleMedium">@style/TextAppearance.App.TitleMedium</item>
</style>

<style name="TextAppearance.App.TitleLarge" parent="TextAppearance.Material3.TitleLarge">
    <item name="fontFamily">@font/rubik</item>
    <item name="android:fontFamily">@font/rubik</item>
</style>

<style name="TextAppearance.App.TitleMedium" parent="TextAppearance.Material3.TitleMedium">
    <item name="fontFamily">@font/rubik</item>
    <item name="android:fontFamily">@font/rubik</item>
</style>

Use default style theme attributes, styles and theme overlays, which applies to all top app bars but does not affect other components:

<style name="Theme.App" parent="Theme.Material3.*.NoActionBar">
    ...
    <item name="toolbarStyle">@style/Widget.App.Toolbar</item>
</style>

<style name="Widget.App.Toolbar" parent="Widget.Material3.Toolbar">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Toolbar</item>
    <item name="titleTextAppearance">@style/TextAppearance.App.TitleLarge</item>
    <item name="subtitleTextAppearance">@style/TextAppearance.App.TitleMedium</item>
</style>

<style name="ThemeOverlay.App.Toolbar" parent="">
    <item name="colorSurface">@color/shrine_pink_100</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
</style>

Use the style in the layout, which affects only this top app bar:

<com.google.android.material.appbar.MaterialToolbar
    ...
    app:title="@string/flow_shirt_blouse"
    app:menu="@menu/top_app_bar_shrine"
    app:navigationIcon="@drawable/ic_close_24dp"
    style="@style/Widget.App.Toolbar"
    />

Contextual action bar

Contextual action bars provide actions for selected items.

Anatomy

Close button (instead of a navigation icon)
Contextual title
Contextual actions
Overflow menu (optional)
Container (not shown)

Key properties

Close button attributes

Element	Attribute	Related method(s)	Default value
Icon	`app:actionModeCloseDrawable` (in app theme)	N/A	`@drawable/abc_ic_ab_back_material`
Color	N/A	N/A	`?attr/colorControlNormal` (as `Drawable` tint)

Contextual title attributes

Element	Attribute	Related method(s)	Default value
Title text	N/A	`setTitle` `getTitle`	`null`
Subtitle text	N/A	`setSubtitle` `getSubtitle`	`null`
Title typography	`app:titleTextStyle`	N/A	`@style/TextAppearance.Material3.ActionBar.Title`
Subtitle typography	`app:subtitleTextStyle`	N/A	`@style/TextAppearance.Material3.ActionBar.Subtitle`

Contextual actions attributes

Element	Attribute	Related method(s)	Default value
Menu	N/A	`menuInflater.inflate` in `ActionMode.Callback`	`null`
Icon color	N/A	N/A	`?attr/colorControlNormal` (as `Drawable` tint)

Element	Attribute	Related method(s)	Default value
Icon	`android:src` and `app:srcCompat` in `actionOverflowButtonStyle` (in app theme)	`setOverflowIcon` `getOverflowIcon`	`@drawable/abc_ic_menu_overflow_material` (before API 23) or `@drawable/ic_menu_moreoverflow_material` (after API 23)
Overflow item typography	`textAppearanceSmallPopupMenu` and `textAppearanceLargePopupMenu` in app theme	N/A	`?attr/textAppearanceTitleMedium`

Container attributes

Element	Attribute	Related method(s)	Default value
Color	`app:background`	N/A	`?attr/actionModeBackground`
Height	`app:height`	N/A	`?attr/actionBarSize`
Overlay window	`app:windowActionModeOverlay` (in app theme)	N/A	`false`

Element	Attribute	Related method(s)	Default value
AdjustViewBounds	`app:logoAdjustViewBounds`	`setLogoAdjustViewBounds` `isLogoAdjustViewBounds`	`false`
ScaleType	`app:logoScaleType`	`setLogoScaleType` `getLogoScaleType`	ImageView's default

Styles

Element	Style	Theme attribute
Default style	`Widget.Material3.ActionMode`	`actionModeStyle`

Adding contextual action bar

API and source code:

ActionMode
- Class definition

The following example shows a contextual action bar with a contextual title, a close icon, two contextual action icons, and an overflow menu:

In res/values/themes.xml:

<style name="Theme.App" parent="Theme.Material3.*.NoActionBar">
    ...
    <item name="windowActionModeOverlay">true</item>
    <item name="actionModeCloseDrawable">@drawable/ic_close_24dp</item>
    <item name="actionBarTheme">@style/ThemeOverlay.Material3.Dark.ActionBar</item>
</style>

In code:

val callback = object : ActionMode.Callback {

    override fun onCreateActionMode(mode: ActionMode?, menu: Menu?): Boolean {
        menuInflater.inflate(R.menu.contextual_action_bar, menu)
        return true
    }

    override fun onPrepareActionMode(mode: ActionMode?, menu: Menu?): Boolean {
        return false
    }

    override fun onActionItemClicked(mode: ActionMode?, item: MenuItem?): Boolean {
        return when (item?.itemId) {
            R.id.share -> {
                // Handle share icon press
                true
            }
            R.id.delete -> {
                // Handle delete icon press
                true
            }
            R.id.more -> {
                // Handle more item (inside overflow menu) press
                true
            }
            else -> false
        }
    }

    override fun onDestroyActionMode(mode: ActionMode?) {
    }
}

val actionMode = startSupportActionMode(callback)
actionMode?.title = "1 selected"

In @menu/contextual_action_bar.xml:

<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <item
        android:id="@+id/share"
        android:icon="@drawable/ic_share_24dp"
        android:title="@string/share"
        android:contentDescription="@string/content_description_share"
        app:showAsAction="ifRoom" />

    <item
        android:id="@+id/delete"
        android:icon="@drawable/ic_delete_24dp"
        android:title="@string/delete"
        android:contentDescription="@string/content_description_delete"
        app:showAsAction="ifRoom" />

    <item
        android:id="@+id/more"
        android:title="@string/more"
        android:contentDescription="@string/content_description_more"
        app:showAsAction="never" />

</menu>

In menu/navigation icons:

<vector
    ...
    android:tint="?attr/colorControlNormal">
    ...
</vector>

Deprecated app bars

There are two deprecated app bars that are no longer recommended:

Medium
Large

The larger collapsing top app bars can be used for longer titles, to house imagery, or to provide a stronger presence to the top app bar.

Medium top app bar

The following example shows a medium collapsing top app bar with a page title, a navigation icon, an action icon, and an overflow menu.

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...>

    <com.google.android.material.appbar.AppBarLayout
        ...
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:fitsSystemWindows="true">

        <com.google.android.material.appbar.CollapsingToolbarLayout
            style="?attr/collapsingToolbarLayoutMediumStyle"
            android:layout_width="match_parent"
            android:layout_height="?attr/collapsingToolbarLayoutMediumSize">

            <com.google.android.material.appbar.MaterialToolbar
                ...
                android:layout_width="match_parent"
                android:layout_height="?attr/actionBarSize"
                android:elevation="0dp" />

        </com.google.android.material.appbar.CollapsingToolbarLayout>

    </com.google.android.material.appbar.AppBarLayout>

    ...

</androidx.coordinatorlayout.widget.CoordinatorLayout>

Large top app bar

The following example shows a large collapsing top app bar with a page title, a navigation icon, an action icon, and an overflow menu.

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...>

    <com.google.android.material.appbar.AppBarLayout
        ...
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:fitsSystemWindows="true">

        <com.google.android.material.appbar.CollapsingToolbarLayout
            style="?attr/collapsingToolbarLayoutLargeStyle"
            android:layout_width="match_parent"
            android:layout_height="?attr/collapsingToolbarLayoutLargeSize">

            <com.google.android.material.appbar.MaterialToolbar
                android:layout_width="match_parent"
                android:layout_height="?attr/actionBarSize"
                ...
                android:elevation="0dp" />

        </com.google.android.material.appbar.CollapsingToolbarLayout>

    </com.google.android.material.appbar.AppBarLayout>

    ...

</androidx.coordinatorlayout.widget.CoordinatorLayout>

49 KiB Raw Permalink Blame History

Top app bars (App bars)

Design & API documentation

Anatomy

M3 Expressive

M3 Expressive update

Key properties

Container attributes

Navigation icon attributes

Title attributes

Action items attributes

Overflow menu attributes

Scrolling behavior attributes

AppBarLayout styles

MaterialToolbar styles

CollapsingToolbarLayout styles

Variants of app bars

Search app bar

Small app bar

Medium flexible app bar

Large flexible app bar

Code implementation

Center aligning app bars

Adding image to collapsing app bars

Adding filled trailing icon button to app bars

Adding a circle to the navigation button

Applying scrolling behavior to app bars

Making app bars accessible

Content descriptions

Status bar and edge-to-edge

Customizing app bars

Theming app bars

App bar theming example

Implementing app bar theming

Contextual action bar

Anatomy

Key properties

Close button attributes

Contextual title attributes

Contextual actions attributes

Overflow menu attributes

Container attributes

Toolbar logo attributes

Styles

Adding contextual action bar

Deprecated app bars

Medium top app bar

Large top app bar

49 KiB

Raw Permalink Blame History

`AppBarLayout` styles

`MaterialToolbar` styles

`CollapsingToolbarLayout` styles