App bars: top

The top app bar displays information and actions relating to the current screen.

Android Web Flutter iOS check

Usage

The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.

It can transform into a contextual action bar.

Principles

Persistent

Top app bars appear at the top of each screen in an app, and can disappear upon scroll.

Guiding

Top app bars provide a reliable way to guide users through an app.

Consistent

Top app bars have a consistent position and content to increase familiarity.


Types

There are regular top app bars and contextual action bars.

Top app bar
Regular
A regular top app bar
Contextual top app bar with menu icon and page title on left, and favorite, search and overflow menu icons on right
Contextual action bar
Contextual action bars provide actions for selected items. A top app bar can transform into a contextual action bar, remaining active until an action is taken or it is dismissed.

Anatomy

The recommended placement of elements in a top app bar for left-to-right languages is:

  • Place navigation on the far left
  • Place any titles to the right of navigation
  • Place contextual actions to the right of navigation
  • Place an overflow menu (if used) to the far right

For right-to-left languages, placement positions should be flipped.

Contextual top app bar with menu icon and page title on left, and favorite, search and overflow menu icons on right
1. Container
2. Navigation icon (optional)
3. Title (optional)
4. Action items (optional)
5. Overflow menu (optional)

Bar

The bar holds the content of the top app bar. A variety of bar heights are available: Prominent top app bars can be used fo

The bar holds the content of the top app bar. A variety of bar heights are available:

  • Regular
  • Prominent
  • Dense (desktop only)
  • Prominent dense (desktop only)

Prominent

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

Regular and prominent top app bars in photos app. Prominent bar height is twice the height of the regular bar.
1. Regular top app bar on mobile
2. Prominent top app bar on mobile

Dense (desktop only)

The top app bar may be condensed on desktop to accommodate denser layouts.

Dense top app bar height is shorter than the regular top app bar in photos app on desktop.
1. Regular top app bar on desktop
2. Dense top app bar on desktop

Prominent dense

Prominent top app bars on desktop can have a dense state to accommodate denser layouts.

The prominent dense app bar’s height is shorter than the prominent top app bar in the photo app.
1. Prominent top app bar on desktop
2. Prominent dense top app bar on desktop

Images in bars

Bars can contain imagery. Prominent top app bars are recommended for image use because they provide more space.

Don’t use imagery that makes top app bar text and icons illegible.

Showing correct use of an image underlay in a top app bar with a simple, monochromatic image.
A prominent top app bar with imagery
The text “Aerial Shots” is hard to read over the image underlay in a top app bar.
Don'tDon’t place imagery in a bar that makes the top app bar’s text and icons illegible.

Navigation icon (optional)

A navigation icon is optional. When it appears in an app bar, it’s aligned on the left of the bar. It can take any of...

A navigation icon is optional. When it appears in an app bar, it’s aligned on the left of the bar.

It can take any of the following forms:

  • A menu icon, which opens a navigation drawer
  • An up arrow, which navigates upward an app’s hierarchy
  • A back arrow, which returns to the previous screen
The navigation icon is at the top left of the app bar.
1. Navigation icon

Title (optional)

The app bar title can be used to describe: By default, titles are left aligned on desktop. The default position of titles on mobile and...

The app bar title can be used to describe:

  • The screen a user is currently on
  • The section the user is currently in
  • The app being used

By default, titles are left aligned on desktop. The default position of titles on mobile and tablet depends on the platform. More information on this is available in cross-platform adaptation.

Wrapped title of “Summer Trip to Kyoto and Tokyo” in prominent app bar in photos app.
DoIf title text is long, use a prominent app bar and wrap the title to two lines.
Wrapped title use of “Vacation photos” in regular top app bar
Don'tDon’t wrap text in a regular top app bar.
Truncated “Vacation photos” text in title
Don'tDon’t truncate text, hiding the full title may cause misunderstanding.
Top app bar with shrunk text size of title “2017 Tokyo Vacation photos”.
Don'tDon’t shrink text to fit on a single line.

Action items and overflow menu (optional)

App actions are placed on the right side of an app bar, either as icons or in an overflow menu. Overflow menus differ across mobile...

App actions are placed on the right side of an app bar, either as icons or in an overflow menu. Overflow menus differ across mobile platforms. For more guidance refer to cross-platform adaptation.

Icon placement

Place most-used actions on the left, progressing towards the least-used actions on the far right. Any remaining actions that don’t fit on the app bar can go into an overflow menu.

Actions move into and out of the overflow menu as the app bar width changes, such as if a device is rotated from landscape to portrait orientation. More guidance on this is available in top app bar behavior.

Top app bar with menu icon and page title on left, and favorite, search and overflow menu icons on right
DoOrder action items by putting the most-used action (1) on the far left, second most used action (2) to its right, and so on. Any remaining or secondary actions should be placed in an overflow menu (3).

Cross-platform adaptation

On iOS, toolbars are called navigation bars and their height is shorter than the Android version. On Android, toolbars are called top app bars.

It’s recommended to use a platform’s default text alignment for toolbar titles, unless multiple action buttons are present.

Android
Titles are left-aligned by default in top app bars.
iOS
Titles are center-aligned by default in navigation bars.
Android
When multiple actions, or even no actions, appear on the right side, top app bar titles are always left-aligned.
iOS
When multiple action buttons are on the right side, or on the home screen of an application, titles may be left-aligned.

Translucency

Material Design uses shadows to express elevation in app bars. In iOS, products can use translucency to differentiate app bars from content.

Android
Use shadow to express elevation.
iOS
Products have the option to use translucency to express elevation in iOS. Use a hairline as a bottom border of the app bar to ensure differentiation between the top app bar and scrolling content.

Behavior

Scrolling

Upon scrolling, the top app bar can remain in place, or transform in the following ways: When the top app bar scrolls, its elevation above...

Upon scrolling, the top app bar can remain in place, or transform in the following ways:

  • Scrolling upward hides the top app bar
  • Scrolling downward reveals the top app bar

When the top app bar scrolls, its elevation above other elements becomes apparent.

The top app bar disappears upon scrolling up, and appears upon scrolling down.
Top app bars can be positioned at the same elevation as content. Upon scroll, they increase elevation and let content scroll behind them.
When scrolling up, prominent top app bars using imagery can transform into normal top app bars. They should not return to prominent mode until the user scrolls back to the top of the page.

Nesting actions

When a screen is resized, the top app bar resizes with it. Actions are consolidated into the overflow menu. The actions move to the overflow...

When a screen is resized, the top app bar resizes with it. Actions are consolidated into the overflow menu.

Action positioning

The actions move to the overflow menu from right to left, making the most-used action the last to be moved to the overflow menu.

As a top app bar is resized, actions move to the overflow menu from right to left.

Scaled down to 62.5%

Contextual action bar

Usage

A top app bar can transform into a contextual action bar to provide contextual actions to selected items. For example, upon user selection of photos...

A top app bar can transform into a contextual action bar to provide contextual actions to selected items. For example, upon user selection of photos from a gallery, the top app bar transforms to a contextual app bar with actions related to the selected photos.

When a top app bar transforms into a contextual action bar, the following changes occur:

  • The bar color changes
  • Navigation icon is replaced with a close icon
  • Top app bar title text converts to contextual action bar text
  • Top app bar actions are replaced with contextual actions

Upon closing, the contextual action bar transforms back into a top app bar.

Top app bar transforming into a contextual action bar

Anatomy

When a top app bar transforms into a contextual action bar, the bar should change color to indicate a change of state.

Contextual action bar with remove, share and delete icons
1. Close button (instead of a navigation icon)
2. Contextual title
3. Contextual actions
4. Overflow menu (optional)

Bar

When a top app bar transforms into a contextual action bar, the bar should change color to indicate a change of state.


Theming

Fortnightly Material Theme

This news app’s top app bar has been customized using Material Theming. Areas of customization include color and typography. Fortnightly is a news app that...

Color

App bar with Politics title, menu, save and search icons
Element Category Attribute Value
Container Surface Color
Opacity
#FFFFFF
100%
Text, icons On Surface Color
Opacity
#000000
100%

Typography

Diagram of headline, subtitle and body typography styles
Element Category Attribute Value
Text H6 Typeface
Font
Size
Case
Merriweather
Bold Italic
20
Title case

Rally Material Theme

This financial app’s top app bar has been customized using Material Theming. Areas of customization include color and typography. Rally is a personal finance app...

Color

Rally top app bar with container, text, icons
Element Category Attribute Value
Container Surface Color
Opacity
#363640
100%
Text On Surface Color
Opacity
#FFFFFF
100%
Icons On Surface Color
Opacity
#FFFFFF
60%

Typography

Diagram of headline, subtitle and body typography styles
Element Category Attribute Value
Text H6 Typeface
Font
Size
Case
Roboto Condensed
Regular
20
Title case

Shrine Material Theme

This retail app’s top app bar has been customized using Material Theming. Areas of customization include color and typography. Shrine is a lifestyle and fashion...

Color

Shrine top app bar with “flow shirt blouse” title with remove, share, shopping cart icons
Element Category Attribute Value
Container Primary Color
Opacity
#FEDBD0
100%
Text, icons On Primary Color
Opacity
#442C2E
100%

Typography

Diagram of headline, subtitle and body typography styles
Element Category Attribute Value
Text H6 Typeface
Font
Size
Case
Rubik
Medium
20
Title case

Specs

Mobile

Regular top app bar

  • Measurement 360
  • Measurement 56
  • Measurement 24
  • Measurement 16
  • Measurement 16
  • Measurement 24
  • Measurement 24
  • Measurement 32
  • Measurement 16
  • Measurement 20
  • Measurement 16
 

Extended top app bar

  • Measurement 24
  • Measurement 128
  • Measurement 16
  • Measurement 28
  • Measurement 24
  • Measurement 24
  • Measurement 16
  • Measurement 72
  • Measurement 360
  • Measurement 16
 

Using top app bars

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.

Making top app bars accessible

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

Content descriptions

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

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:

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

Types

There are two types of top app bar: 1. Regular top app bar, 2. Contextual action bar

Regular and contextual app bars

Regular top app bar

The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.

Regular top app bar examples

API and source code:

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

Top app bar with purple background, white icons, and page title

In the layout:

In @menu/top_app_bar.xml:

In menu/navigation icons:

In code:

Note: The above example is the recommended approach and, in order for it to work, you need to be using a Theme.MaterialComponents.* theme containing the NoActionBar segment (eg. Theme.MaterialComponents.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.

Applying scrolling behavior to the 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:

The following example shows the top app bar disappearring upon scrolling up, and appearring upon scrolling down.

In the layout:

Converting to a prominent top app bar

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

App bar with purple background and white icons with the page title on a
newline below the icons

In the layout:

In res/values/type.xml:

Adding an image to the prominent top app bar

The following example shows a prominent top app bar with an image background, a page title, a navigation icon, two action icons, and an overflow menu.

App bar with red background and white icons. The page title is on a newline
below the icons

In the layout:

In res/values/themes.xml:

Applying scrolling behavior to the prominent top app bar

The following example shows, when scrolling up, the prominent top app bar transforming into a normal top app bar.

In the layout:

Anatomy and Key properties

Regular app bar anatomy diagram

  1. Container
  2. Navigation icon (optional)
  3. Title (optional)
  4. Action items (optional)
  5. Overflow menu (optional)

Container attributes

ElementAttributeRelated method(s)Default value
Colorandroid:backgroundsetBackground
getBackground
?attr/colorPrimary
MaterialToolbar Elevationandroid:elevationsetElevation
getElevation
4dp
AppBarLayout elevationandroid:stateListAnimatorsetStateListAnimator
getStateListAnimator
0dp to 4dp (see all states)
ElementAttributeRelated method(s)Default value
MaterialToolbar iconapp:navigationIconsetNavigationIcon
getNavigationIcon
null
MaterialToolbar icon colorapp:navigationIconTintsetNavigationIconTint?attr/colorControlNormal (as Drawable tint)

Title attributes

ElementAttributeRelated method(s)Default value
MaterialToolbar title textapp:titlesetTitle
getTitle
null
MaterialToolbar subtitle textapp:subtitlesetSubtitle
getSubtitle
null
MaterialToolbar title colorapp:titleTextColorsetTitleTextColor?android:attr/textColorPrimary
MaterialToolbar subtitle colorapp:subtitleTextColorsetSubtitleTextColor?android:attr/textColorSecondary
MaterialToolbar title typographyapp:titleTextAppearancesetTitleTextAppearance?attr/textAppearanceHeadline6
MaterialToolbar subtitle typographyapp:subtitleTextAppearancesetSubtitleTextAppearance?attr/textAppearanceSubtitle1
MaterialToolbar title centeringapp:titleCenteredsetTitleCenteredfalse
MaterialToolbar subtitle centeringapp:subtitleCenteredsetSubtitleCenteredfalse
CollapsingToolbarLayout collapsed title typographyapp:collapsedTitleTextAppearancesetCollapsedTitleTextAppearance@style/TextAppearance.AppCompat.Widget.ActionBar.Title
CollapsingToolbarLayout expanded title typographyapp:expandedTitleTextAppearancesetExpandedTitleTextAppearance@style/TextAppearance.Design.CollapsingToolbar.Expanded
CollapsingToolbarLayout collapsed title colorandroid:textColor (in app:collapsedTitleTextAppearance)setCollapsedTitleTextColor?android:attr/textColorPrimary
CollapsingToolbarLayout expanded title colorandroid:textColor (in app:expandedTitleTextAppearance)setExpandedTitleTextColor?android:attr/textColorPrimary
CollapsingToolbarLayout expanded title marginsapp:expandedTitleMargin*setExpandedTitleMargin*32dp
CollapsingToolbarLayout title max linesapp:maxLinessetMaxLines
getMaxLines
1

Action items attributes

ElementAttributeRelated method(s)Default value
MaterialToolbar menuapp:menuinflateMenu
getMenu
null
MaterialToolbar icon colorN/AN/A?attr/colorControlNormal (as Drawable tint)

Overflow menu attributes

ElementAttributeRelated method(s)Default value
MaterialToolbar iconandroid: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 themeapp:popupThemesetPopupTheme
getPopupTheme
@style/ThemeOverlay.MaterialComponents.*
MaterialToolbar overflow item typographytextAppearanceSmallPopupMenu and textAppearanceLargePopupMenu in app:popupTheme or app themeN/A?attr/textAppearanceSubtitle1

Scrolling behavior attributes

ElementAttributeRelated method(s)Default value
MaterialToolbar or CollapsingToolbarLayout scroll flagsapp:layout_scrollFlagssetScrollFlags
getScrollFlags
(on AppBarLayout.LayoutParams)
noScroll
MaterialToolbar collapse modeapp:collapseModesetCollapseMode
getCollapseMode
(on CollapsingToolbar)
none
CollapsingToolbarLayout content scrim colorapp:contentScrimsetContentScrim
setContentScrimColor
setContentScrimResource
getContentScrim
null
CollapsingToolbarLayout status bar scrim colorapp:statusBarScrimsetStatusBarScrim
setStatusBarScrimColor
setStatusBarScrimResource
getStatusBarScrim
?attr/colorPrimaryDark
CollapsingToolbarLayout scrim animation durationapp:scrimAnimationDurationsetScrimAnimationDuration
getScrimAnimationDuration
600
AppBarLayout lift on scrollapp:liftOnScrollsetLiftOnScroll
isLiftOnScroll
false

AppBarLayout styles

ElementStyle
Primary background color styleWidget.MaterialComponents.AppBarLayout.Primary
Surface background color styleWidget.MaterialComponents.AppBarLayout.Surface
Primary (light theme) or surface (dark theme) background color styleWidget.MaterialComponents.AppBarLayout.PrimarySurface

Default style theme attribute: ?attr/appBarLayoutStyle

MaterialToolbar styles

ElementStyle
Default styleWidget.MaterialComponents.Toolbar
Primary background color styleWidget.MaterialComponents.Toolbar.Primary
Surface background color styleWidget.MaterialComponents.Toolbar.Surface
Primary (light theme) or surface (dark theme) background color styleWidget.MaterialComponents.Toolbar.PrimarySurface

Default style theme attribute: ?attr/toolbarStyle

CollapsingToolbarLayout styles

ElementStyle
Default styleWidget.Design.CollapsingToolbar

Default style theme attribute: collapsingToolbarLayoutStyle

See the full list of styles and attrs.

Contextual action bar

Contextual action bars provide actions for selected items. A top app bar can transform into a contextual action bar, remaining active until an action is taken or it is dismissed.

Contextual action bar example

API and source code:

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

Contextual action bar example with dark grey background, white icons and "1
selected".

In res/values/themes.xml:

In res/values/styles.xml:

In code:

In @menu/contextual_action_bar.xml:

In menu/navigation icons:

Anatomy and Key properties

Contextual action bar anatomy diagram

  1. Close button (instead of a navigation icon)
  2. Contextual title
  3. Contextual actions
  4. Overflow menu (optional)
  5. Container (not shown)

Close button attributes

ElementAttributeRelated method(s)Default value
Iconapp:actionModeCloseDrawable (in app theme)N/A@drawable/abc_ic_ab_back_material
ColorN/AN/A?attr/colorControlNormal (as Drawable tint)

Contextual title attributes

ElementAttributeRelated method(s)Default value
Title textN/AsetTitle
getTitle
null
Subtitle textN/AsetSubtitle
getSubtitle
null
Title typographyapp:titleTextStyleN/A@style/TextAppearance.AppCompat.Widget.ActionMode.Title
Subtitle typographyapp:subtitleTextStyleN/A@style/TextAppearance.AppCompat.Widget.ActionMode.Subtitle

Contextual actions attributes

ElementAttributeRelated method(s)Default value
MenuN/AmenuInflater.inflate in ActionMode.Callbacknull
Icon colorN/AN/A?attr/colorControlNormal (as Drawable tint)

Overflow menu attributes

ElementAttributeRelated method(s)Default value
Iconandroid: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 typographytextAppearanceSmallPopupMenu and textAppearanceLargePopupMenu in app themeN/A?attr/textAppearanceSubtitle1

Container attributes

ElementAttributeRelated method(s)Default value
Colorapp:backgroundN/A?attr/actionModeBackground
Heightapp:heightN/A?attr/actionBarSize
Overlay windowapp:windowActionModeOverlay (in app theme)N/Afalse

Styles

ElementStyle
Default styleWidget.AppCompat.ActionMode

Default style theme attribute: actionModeStyle

Theming the top app bar

The top app bar supports Material Theming and can be customized in terms of color, typography and shape.

Top app bar theming example

API and source code:

The following example shows a regular top app bar with Material Theming.

"Top app bar theming with pink and brown colors"

Implementing top app bar theming

Using theme attributes in res/values/styles.xml (themes all top app bars and affects other components):

or using default style theme attributes, styles and theme overlays (themes all top app bars but does not affect other components):

or using one the style in the layout (affects only this top app bar):

No Android implementation guidance available

Using the top app bar

Installation

Styles

JavaScript Instantiation

Note: See Importing the JS component for more information on how to import JavaScript.

Regular top app bar

The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.

Regular top app bar example

Top app bars can contain action items which are placed on the side opposite the navigation icon. You must also attach the mdc-icon-button class to both the mdc-top-app-bar__navigation-icon and the mdc-top-app-bar__action-item elements in order to get the correct styles applied.

For further documentation on icons, please see the mdc-icon-button docs.

Contextual action bar

A top app bar can transform into a contextual action bar to provide contextual actions to selected items. For example, upon user selection of photos from a gallery, the top app bar transforms to a contextual app bar with actions related to the selected photos.

When a top app bar transforms into a contextual action bar, the following changes occur:

  • The bar color changes
  • Navigation icon is replaced with a close icon
  • Top app bar title text converts to contextual action bar text
  • Top app bar actions are replaced with contextual actions
  • Upon closing, the contextual action bar transforms back into a top app bar.

Contextual action bar example

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

Other Variants

Short

Short top app bars are top app bars that can collapse to the navigation icon side when scrolled.

Note: Short top app bars should be used with no more than 1 action item.

Short - always closed

Short top app bars can be configured to always appear collapsed by applying the mdc-top-app-bar--short-collapsed before instantiating the component :

Fixed

Fixed top app bars stay at the top of the page and elevate above the content when scrolled.

Prominent

The prominent top app bar is taller.

Dense

The dense top app bar is shorter.

Style customization

CSS classes

ClassDescription
mdc-top-app-barMandatory.
mdc-top-app-bar--fixedClass used to style the top app bar as a fixed top app bar.
mdc-top-app-bar--fixed-adjustClass used to style the content below the top app bar to prevent the top app bar from covering it.
mdc-top-app-bar--prominentClass used to style the top app bar as a prominent top app bar.
mdc-top-app-bar--prominent-fixed-adjustClass used to style the content below the prominent top app bar to prevent the top app bar from covering it.
mdc-top-app-bar--denseClass used to style the top app bar as a dense top app bar.
mdc-top-app-bar--dense-fixed-adjustClass used to style the content below the dense top app bar to prevent the top app bar from covering it.
mdc-top-app-bar--dense-prominent-fixed-adjustClass used to style the content below the top app bar when styled as both dense and prominent, to prevent the top app bar from covering it.
mdc-top-app-bar--shortClass used to style the top app bar as a short top app bar.
mdc-top-app-bar--short-collapsedClass used to indicate the short top app bar is collapsed.
mdc-top-app-bar--short-fixed-adjustClass used to style the content below the short top app bar to prevent the top app bar from covering it.

Sass mixins

MixinDescription
ink-color($color)Sets the ink color of the top app bar.
icon-ink-color($color)Sets the ink color of the top app bar icons.
fill-color($color)Sets the fill color of the top app bar.
fill-color-accessible($color)Sets the fill color of the top app bar and automatically sets a high-contrast ink color.
short-shape-radius($radius, $rtl-reflexive)Sets the rounded shape to short top app bar variant (when it is collapsed) with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to true.

MDCTopAppBar properties and methods

Method SignatureDescription
setScrollTarget(target: element) => voidSets scroll target to different DOM node (default is window).

Events

Event NameEvent Data StructureDescription
MDCTopAppBar:navNoneEmits when the navigation icon is clicked.

Usage within web frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Top App Bar for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCTopAppBarAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element of the component.
removeClass(className: string) => voidRemoves a class from the root element of the component.
hasClass(className: string) => booleanChecks if the root element of the component has the given className.
setStyle(property: string, value: string) => voidSets the specified CSS property to the given value on the root element.
getTopAppBarHeight() => numberGets the height in px of the top app bar.
getViewportScrollY() => numberGets the number of pixels that the content of body is scrolled from the top of the page.
getTotalActionItems() => numberGets the number of action items in the top app bar.
notifyNavigationIconClicked() => voidEmits a custom event MDCTopAppBar:nav when the navigation icon is clicked.

Foundations

MDCTopAppBarBaseFoundation, MDCTopAppBarFoundation, MDCFixedTopAppBarFoundation and MDCShortTopAppBarFoundation

All foundations provide the following methods:

Method SignatureDescription
handleTargetScroll() => voidHandles scroll event on specified scrollTarget (defaults to window).
handleWindowResize() => voidHandles resize event on window.
handleNavigationClick() => voidHandles click event on navigation icon.

MDCShortTopAppBarFoundation

In addition to the methods above, the short variant provides the following public methods and properties:

Method SignatureDescription
setAlwaysCollapsed(value: boolean) => voidWhen value is true, sets the short top app bar to always be collapsed.
getAlwaysCollapsed() => booleanGets if the short top app bar is in the "always collapsed" state.
PropertyValue TypeDescription
isCollapsedboolean (read-only)Indicates whether the short top app bar is in the collapsed state.
No Web implementation guidance available

Using the top app bar

The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.

A regular top app bar can transform into a contextual action bar.

Before you can use Material buttons, you need to import the Material Components package for Flutter:

You need to use MaterialApp.

For more information on getting started with the Material for Flutter, go to the Flutter Material library page.

Making the top app bar accessible

Flutter's APIs support accessibility setting for large fonts, screen readers, and sufficient contrast. For more information, go to Flutter's accessibility and internationalization pages.

For more guidance on writing labels, go to our page on how to write a good accessibility label.

Types

There are two types of top app bar: 1. regular top app bar 2. contextual action bar

Regular app bar: purple background, white text and icons and Contextual action bar: black background, white text and icons

Regular top app bar

The top app bar provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.

Regular top app bar example

AppBar

The following example shows a top app bar with a page title, a navigation icon, two action icons, and an overflow menu:

Top app bar with nav icon, page title, favorite icon, and search icon

Anatomy and Key properties for top app bar

Regular app bar anatomy diagram

  1. Container (optional)
  2. Navigation icon (optional)
  3. Title (optional)
  4. Action items (optional)
  5. Overflow menu (optional)

Container for top app bar

 Property
Colorcolor parameter
Stroke colorIn leading parameter, use Icon widget. Set color
Shapeshape parameter
Elevationelevation parameter
 Property
IconIn leading parameter, use IconButton Widget
ColorIn leading parameter, use IconButton Widget and set parameter color
SizeIn leading parameter, use IconButton Widget and set parameter iconSize
GravitytitleSpacing parameter
PaddingWrap Icon widget with Padding widget

Title for top app bar (optional)

 Property
Text labelIn title parameter, use Text widget
ColorIn title parameter, use Text Widget and and set parameter style
TypographyIn title parameter, use Text Widget and and set parameter style

Action item for top app bar (optional)

 Property
IconIn action parameter, use IconButton widget and set parameter icon
ColorIn action parameter, use IconButton widget and set parameter color OR set actionIconsTheme
SizeIn action parameter, use IconButton widget and set parameter iconSize OR set actionIconsTheme
PaddingWrap IconButton widget with Padding widget

Overflow menu for top app bar (optional)

 Property
IconIn action parameter, add IconButton widget to the end of Widget list and set parameter icon within IconButton
ColorIn action parameter, add IconButton widget to the end of Widget list and set parameter color within IconButton
SizeIn action parameter, add IconButton widget to the end of Widget list and set parameter iconSize within IconButton
PaddingIn action parameter, add IconButton widget to the end of Widget list and wrap that Widget with a Padding widget

Contextual action bar

A top app bar can transform into a contextual action bar to provide contextual actions to selected items. For example, upon user selection of photos from a gallery, the top app bar transforms to a contextual app bar with actions related to the selected photos.

When a top app bar transforms into a contextual action bar, the following changes occur:

  • The bar color changes
  • Navigation icon is replaced with a close icon
  • Top app bar title text converts to contextual action bar text
  • Top app bar actions are replaced with contextual actions
  • Upon closing, the contextual action bar transforms back into a top app bar.

Contextual action bar example

AppBar

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

Contextual top app bar with close button, download, garbage, and overflow menu icons

Anatomy and Key properties for contextual action bar

Contextual action bar anatomy diagram

  1. Close Button (optional)
  2. Contextual title (optional)
  3. Contextual action items (optional)
  4. Overflow menu (optional)

Close Button for contextual action bar (optional)

 Property
IconIn leading parameter, use IconButton Widget
ColorIn leading parameter, use IconButton Widget and set parameter color
SizeIn leading parameter, use IconButton Widget and set parameter iconSize
GravitytitleSpacing parameter
PaddingWrap Icon wiget with Padding widget

Contextual title for contextual action bar (optional)

 Property
Text labelIn title parameter, use Text widget
ColorIn title parameter, use Text Widget and and set parameter style
TypographyIn title parameter, use Text Widget and and set parameter style

Contextual action items for contextual action bar (optional)

 Property
IconIn action parameter, use IconButton widget and set parameter icon
ColorIn action parameter, use IconButton widget and set parameter color OR set actionIconsTheme
SizeIn action parameter, use IconButton widget and set parameter iconSize OR set actionIconsTheme
PaddingWrap IconButton widget with Padding widget

Overflow menu for contextual action bar (optional)

 Property
IconIn action parameter, add IconButton widget to the end of Widget list and set parameter icon within IconButton
ColorIn action parameter, add IconButton widget to the end of Widget list and set parameter color within IconButton
SizeIn action parameter, add IconButton widget to the end of Widget list and set parameter iconSize within IconButton
PaddingIn action parameter, add IconButton widget to the end of Widget list and wrap that Widget with a Padding widget

Theming a top app bar

The top app bar supports Material Theming and can be customized in terms of color, typography and shape.

Top app bar theming example

Top app bar with Shrine theming
Contextual app bar with Shrine theming

No Flutter implementation guidance available

Using top app bars

Installing

In order to use top app bars, first add the AppBar subspec to your Podfile:

Then, run the installer:

After that, import the relevant target or file.

Swift

Objective-C

Top app bar classes

Top app bars are composed of the following components:

A top app bar is essentially a FlexibleHeader with a HeaderStackView and NavigationBar added as subviews.

MDCAppBarViewController is the primary API for the component. All integration strategies will make use of it in some manner. Top app bars rely on each view controller creating and managing their own MDCAppBarViewController instances. This differs from UIKit, where many view controllers in a stack share a single UINavigationBar instance.

Making top app bars accessible

Because the app bar mirrors the state of your view controller's navigationItem, making it accessible often does not require any extra work.

See the following examples:

Swift

Objective-C

Regular top app bar

Example of an iOS regular top app bar

Regular top app bars are the only top app bars supported on iOS.

Top app bar examples

Example with view controller containment, as a navigation controller

The easiest integration path for using the app bar is through the MDCAppBarNavigationController. This API is a subclass of UINavigationController that automatically adds an MDCAppBarViewController instance to each view controller that is pushed onto it, unless an app bar or flexible header already exists.

When using the MDCAppBarNavigationController you will, at a minimum, need to configure the added app bar's background color using the delegate.

Swift

Objective-C

Example with view controller containment, as a child

MDCAppBarViewController instances can be added as children to other view controllers. In this scenario, the parent view controller is often the object that creates and manages the MDCAppBarViewController instance. This allows the parent view controller to configure the app bar directly.

You'll typically push the parent onto a navigation controller, in which case you will also hide the navigation controller's navigation bar using the UINavigationController method -setNavigationBarHidden:animated:.

Swift

Objective-C

Example with view controller containment, as a container

There are cases where adding an MDCAppBarViewController as a child is not possible, most notably:

  • When using UIPageViewController. UIPageViewController's view is a horizontally paging scroll view, meaning there is no fixed view to which an app bar could be added.
  • When using any other view controller that animates its content horizontally without providing a fixed, non-horizontally-moving parent view.

In such cases, using MDCAppBarContainerViewController is preferred. MDCAppBarContainerViewController is a simple container view controller that places a content view controller as a sibling to an MDCAppBarViewController.

Note: the trade off to using this API is that it will affect your view controller hierarchy. If the view controller makes any assumptions about its parent view controller or its navigationController properties then these assumptions may break once the view controller is wrapped.

You'll typically push the container view controller onto a navigation controller, in which case you will also hide the navigation controller's navigation bar using UINavigationController's -setNavigationBarHidden:animated:.

Swift

Objective-C

Example tracking a scroll view

The flexible header can be provided with a tracking scroll view. This allows the flexible header to expand, collapse, and shift off-screen in reaction to the tracking scroll view's delegate events.

Important: When using a tracking scroll view you must forward the relevant UIScrollViewDelegate events to the flexible header.

Follow these steps to hook up a tracking scroll view:

Step 1: Set the tracking scroll view.

In your -viewDidLoad, set the trackingScrollView property on the header view:

Swift

Objective-C

scrollView might be a table view, collection view, or a plain UIScrollView.

iOS 13 Collection Considerations

iOS 13 changed the behavior of the contentInset of a collection view by triggering a layout. This may affect your app if you have not yet registered cells for reuse yet. Our recomendation is to use view controller composition by making your collection view controller a child view controller. If this is not possible then ensure the correct order of operations by registering cell reuse identifiers before setting the Flexible Header's trackingScrollView.

Step 2: Forward UIScrollViewDelegate events to the Header View.

There are two ways to forward scroll events.

Option 1: if your controller does not need to respond to UIScrollViewDelegate events and you're using either a plain UIScrollView or a UITableView you can set your MDCFlexibleHeaderViewController instance as the scroll view's delegate.

Swift

Objective-C

Option 2: implement the required UIScrollViewDelegate methods and forward them to the MDCFlexibleHeaderView instance. This is the most flexible approach and will work with any UIScrollView subclass.

Swift

Objective-C

Enabling observation of the tracking scroll view

If you do not require the flexible header's shift behavior, then you can avoid having to manually forward UIScrollViewDelegate events to the flexible header by enabling observesTrackingScrollViewScrollEvents on the flexible header view. Observing the tracking scroll view allows the flexible header to over-extend, if enabled, and allows the header's shadow to show and hide itself as the content is scrolled.

Note: if you support pre-iOS 11 then you will also need to explicitly clear your tracking scroll view in your deinit/dealloc method.

Swift

Objective-C

Note: if observesTrackingScrollViewScrollEvents is enabled then you can neither enable shift behavior nor manually forward scroll view delegate events to the flexible header.

UINavigationItem support

The app bar begins mirroring the state of your view controller's navigationItem in the provided navigationBar once you call addSubviewsToParent.

Learn more by reading the Navigation Bar section on Observing UINavigationItem instances. Notably: read the section on "Exceptions" to understand which UINavigationItem are not supported.

Interactive background views

Scenario: you've added a background image to your app bar and you'd now like to be able to tap the background image.

This is not trivial to do with the app bar APIs due to considerations being discussed in Issue #184.

The heart of the limitation is that we're using a view (headerStackView) to lay out the Navigation Bar. If you add a background view behind the headerStackView instance then headerStackView will end up eating all of your touch events.

Until Issue #184 is resolved, our recommendation for building interactive background views is the following:

  1. Do not use the component.
  2. Create your own Flexible Header. Learn more by reading the Flexible Header Usage docs.
  3. Add your views to this flexible header instance.
  4. Create a Navigation Bar if you need one. Treat it like any other custom view.

Adjusting the top layout guide of a view controller

If your content view controller depends on the top layout guide being adjusted — e.g. if the content does not have a tracking scroll view and therefore relies on the top layout guide to perform layout calculations — then you should consider setting topLayoutGuideViewController to the content view controller.

Setting this property does two things:

  1. Adjusts the view controller's topLayoutGuide property to take the flexible header into account (most useful pre-iOS 11).
  2. On iOS 11 and up — if there is no tracking scroll view — also adjusts the additionalSafeAreaInsets property to take the flexible header into account.

Note:topLayoutGuideAdjustmentEnabled is automatically enabled if this property is set.

Swift

Objective-C

Behavioral flags

A behavioral flag is a temporary API that is introduced to allow client teams to migrate from an old behavior to a new one in a graceful fashion. Behavioral flags all go through the following life cycle:

  1. The flag is introduced. The default is chosen such that clients must opt in to the new behavior.
  2. After some time, the default changes to the new behavior and the flag is marked as deprecated.
  3. After some time, the flag is removed.

The app bar component and its dependencies include a variety of flags that affect the behavior of the MDCAppBarViewController. Many of these flags represent feature flags that we are using to allow client teams to migrate from an old behavior to a new, usually less-buggy one.

You are encouraged to set all of the behavioral flags immediately after creating an instance of the app bar.

The minimal set of recommended flag values are:

Swift

Objective-C

Removing safe area insets from the min/max heights

The minimum and maximum height values of the flexible header view assume by default that the values include the top safe area insets value. This assumption no longer holds true on devices with a physical safe area inset and it never held true when flexible headers were shown in non full screen settings (such as popovers on iPad).

This behavioral flag is enabled by default, but will eventually be disabled by default and the flag will eventually be removed.

Swift

Objective-C

Enabling top layout guide adjustment

The topLayoutGuideAdjustmentEnabled behavior flag affects topLayoutGuideViewController. Setting topLayoutGuideAdjustmentEnabled to YES enables the new behavior.

topLayoutGuideAdjustmentEnabled is disabled by default, but will eventually be enabled by default and the flag will eventually be removed.

Swift

Objective-C

Enabling inferred top safe area insets

Prior to this behavioral flag, the flexible header always assumed that it was presented in a full-screen capacity, meaning it would be placed directly behind the status bar or device bezel (such as the iPhone X's notch). This assumption does not support extensions and iPad popovers.

Enabling the inferTopSafeAreaInsetFromViewController flag tells the flexible header to use its view controller ancestry to extract a safe area inset from its context, instead of relying on assumptions about placement of the header.

This behavioral flag is disabled by default, but will eventually be enabled by default and the flag will eventually be removed.

Swift

Objective-C

Note: if this flag is enabled and you've also provided a topLayoutGuideViewController, take care that the topLayoutGuideViewController is not a direct ancestor of the flexible header or your app will enter an infinite loop. As a general rule, your topLayoutGuideViewController should be a sibling to the flexible header.

See the FlexibleHeader documentation for additional usage guides.

Anatomy and Key properties

Regular app bar anatomy diagram

  1. Container
  2. Navigation icon (optional)
  3. Title (optional)
  4. Action items (optional)
  5. Overflow menu (optional)

Container attributes

 AttributeRelated method(s)Default value
ColorheaderView.backgroundColor-setBackgroundColor:
-backgroundColor
Primary color
ElevationheaderView.elevation-setElevation:
-elevation
4
 AttributeRelated method(s)Default value
Icons-[UIViewController navigationItem]-setLeftBarButtonItems:
-leftBarButtonItems
-setRightBarButtonItems:
-rightBarButtonItems
nil

Title attributes

 AttributeRelated method(s)Default value
Title text-[UIViewController navigationItem]-setTitle:
-title
nil
Title colornavigationBar.titleTextColor-setTitleTextColor:
-titleTextColor
On primary color
Title fontnavigationBar.titleFont-setTitleFont:
-titleFont
Headline 6

Action items attributes

 AttributeRelated method(s)Default value
Icons-[UIViewController navigationItem]-setLeftBarButtonItems:
-leftBarButtonItems
-setRightBarButtonItems:
-rightBarButtonItems
nil

Overflow menu attributes

 AttributeRelated method(s)Default value
Icons-[UIViewController navigationItem]-setLeftBarButtonItems:
-leftBarButtonItems
-setRightBarButtonItems:
-rightBarButtonItems
nil

Theming

MDCAppBarViewController supports Material Theming using a Container Scheme. To theme your app bar, add the AppBar+Theming subspec to your Podfile:

Then run the installer:

There are two variants for Material Theming of an app bar. The Surface Variant colors the app bar background to be surfaceColor and the Primary Variant colors the app bar background to be primaryColor.

Swift

Objective-C

Migration guides

Migration guide: MDCAppBar to MDCAppBarViewController

MDCAppBarViewController is a direct replacement for MDCAppBar. The migration essentially looks like so:

MDCAppBarViewController is a subclass of MDCFlexibleHeaderViewController, meaning you configure an MDCAppBarViewController instance exactly the same way you'd configure an MDCFlexibleHeaderViewController instance.

MDCAppBar also already uses MDCAppBarViewController under the hood so you can directly replace any references of appBar.headerViewController with appBarViewController.

Swift find and replace recommendations

FindReplace
let appBar = MDCAppBar()let appBarViewController = MDCAppBarViewController()
self.addChildViewController(appBar.headerViewController)self.addChildViewController(appBarViewController)
appBar.addSubviewsToParent()view.addSubview(appBarViewController.view)
appBarViewController.didMove(toParentViewController: self)
self.appBar.headerViewControllerself.appBarViewController

Objective-C find and replace recommendations

FindReplace
MDCAppBar *appBar;MDCAppBarViewController *appBarViewController;
appBar = [[MDCAppBar alloc] init]appBarViewController = [[MDCAppBarViewController alloc] init]
addChildViewController:appBar.headerViewControlleraddChildViewController:appBarViewController
[self.appBar addSubviewsToParent];[self.view addSubview:self.appBarViewController.view];
[self.appBarViewController didMoveToParentViewController:self];

Example migrations

Unsupported

Color Theming

You can theme an app bar with your app's color scheme using the ColorThemer extension.

You must first add the Color Themer extension to your project:

Swift

Objective-C

Typography Theming

You can theme an app bar with your app's typography scheme using the TypographyThemer extension.

You must first add the Typography Themer extension to your project:

Swift

Objective-C

No iOS implementation guidance available

Up next