material-components_material-components-android/docs/components/TabLayout.md

Tab Layout

TabLayout provides a horizontal layout to display tabs. The layout handles interactions for a group of tabs including:

• scrolling behavior,
• (swipe) gestures,
• tab selection,
• animations,
• and alignment.

The Android Developers site provides detailed documentation on implementing TabLayout.

Design & API Documentation

• Material Design guidelines: Tabs
• Class definition
• Class overview

Usage

To use a TabLayout with a static number of tabs, define each tab as a TabItem directly in the layout.

<com.google.android.material.tabs.TabLayout
    android:id="@+id/tabs"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">

  <com.google.android.material.tabs.TabItem
      android:icon="@drawable/ic_icon_a_24"
      android:text="@string/tab_a_label"/>
  <com.google.android.material.tabs.TabItem
      android:icon="@drawable/ic_icon_b_24"
      android:text="@string/tab_b_label"/>
  <com.google.android.material.tabs.TabItem
      android:icon="@drawable/ic_icon_c_24"
      android:text="@string/tab_c_label"/>

</com.google.android.material.tabs.TabLayout>

A tab layout should be used above the content associated with the respective tabs and lets the user quickly change between content views. These content views are often held in a ViewPager.

Use setupWithViewPager(ViewPager) to link a TabLayout with a ViewPager. The individual tabs in the TabLayout will be automatically populated with the page titles from the PagerAdapter.

ViewPager pager;
TabLayout tabs = (TabLayout) findViewById(R.id.tabs);

tabs.setupWithViewPager(pager);

Alternatively, you can add a TabLayout to a ViewPager in XML:

<androidx.viewpager.widget.ViewPager
    android:layout_width="match_parent"
    android:layout_height="match_parent">

  <com.google.android.material.tabs.TabLayout
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:layout_gravity="top" />

</androidx.viewpager.widget.ViewPager>

Badges

TabLayout supports displaying icon and number badges.

// Creates and initializes an instance of BadgeDrawable associated with a tab.
// Subsequent calls to this method will reuse the existing BadgeDrawable.
// This method does not guarantee that the badge is visible.
BadgeDrawable badge = tablayout.getTabAt(0).getOrCreateBadge();
badge.setVisible(true);
// Optionally show a number.
badge.setNumber(99);

NOTE: Don't forget to remove any BadgeDrawables that are no longer needed.

tablayout.getTabAt(0).removeBadge();

Best Practice: If you only need to temporarily hide the badge(e.g. until the next notification is received), the recommended/lightweight alternative is to change the visibility of the BadgeDrawable instead.

Please see BadgeDrawable for details on how to update the badge content being displayed.

Material Styles

Using TabLayout with an updated Material theme (Theme.MaterialComponents) will provide the correct updated Material styles to your tabs by default. If you need to use updated Material tabs and your application theme does not inherit from an updated Material theme, you can apply one of the updated Material styles directly to your widget in XML.

Updated Material Style (Default)

The updated Material TabLayout style consists of updated icon and label tints, ripple color, and ripple shape.

<com.google.android.material.tabs.TabLayout
    style="@style/Widget.MaterialComponents.TabLayout"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

Colored Material Style

The colored Material TabLayout style consists of updated background color based on ?attr/colorPrimary.

<com.google.android.material.tabs.TabLayout
    style="@style/Widget.MaterialComponents.TabLayout.Colored"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

Legacy Material Style

<com.google.android.material.tabs.TabLayout
    style="@style/Widget.Design.TabLayout"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

Attributes

Feature	Relevant attributes
Size	app:tabMinWidth app:tabMaxWidth
Scroll	app:tabMode
Centered	app:tabGravity
Background	app:tabBackground
Icon	app:tabIconTint app:tabIconTintMode
Label	app:tabInlineLabel app:tabTextAppearance app:tabTextColor app:tabSelectedTextColor
Indicator	app:tabIndicatorColor app:tabIndicatorHeight app:tabIndicator app:tabIndicatorGravity app:tabIndicatorFullWidth
Position	app:tabContentStart app:tabPaddingStart app:tabPaddingTop app:tabPaddingEnd app:tabPaddingBottom app:tabPadding
Ripple	app:tabRippleColor

Theme Attribute Mapping

Updated Material Style (Default)

style="@style/Widget.MaterialComponents.TabLayout"

Component Attribute	Default Theme Attribute Value
tabTextAppearance	textAppearanceButton
android:background	colorSurface
tabTextColor (selected)	colorPrimary
tabTextColor	colorOnSurface at 60% opacity
tabIconTint (selected)	colorPrimary
tabIconTint	colorOnSurface at 60% opacity
tabRippleColor	colorPrimary
tabIndicatorColor	colorPrimary

Colored Material Style

style="@style/Widget.MaterialComponents.TabLayout.Colored"

Component Attribute	Default Theme Attribute Value
tabTextAppearance	textAppearanceButton
android:background	colorPrimary
tabTextColor (selected)	colorOnPrimary
tabTextColor	colorOnPrimary at 60% opacity
tabIconTint (selected)	colorOnPrimary
tabIconTint	colorOnPrimary at 60% opacity
tabRippleColor	colorOnPrimary
tabIndicatorColor	colorOnPrimary

Legacy Material Style

style="@style/Widget.Design.TabLayout"

The legacy Material style of TabLayout does not make use of our new theming attributes.