Skip to content

Tabs.md

Latest commit

 

History

History
471 lines (357 loc) · 18.9 KB

Tabs.md

File metadata and controls

471 lines (357 loc) · 18.9 KB

Tabs

Tabs organize content across different screens, data sets, and other interactions.

Tab types

Contents

Using tabs

Before you can use Material tabs, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Basic usage

Three fixed tabs with one tab selected.

A TabLayout can be added to a layout like so:

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

    ...

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

TabItems can then be added as children of the TabLayout and adjusted as needed:

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

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/text_label_1"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/text_label_2"
        />

    ...

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

Changes to tab selection can be observed like so:

tabLayout.addOnTabSelectedListener(object : TabLayout.OnTabSelectedListener {

    override fun onTabSelected(tab: TabLayout.Tab?) {
        // Handle tab select
    }

    override fun onTabReselected(tab: TabLayout.Tab?) {
        // Handle tab reselect
    }

    override fun onTabUnselected(tab: TabLayout.Tab?) {
        // Handle tab unselect
    }
})

Making tabs accessible

The Android tab components support screen reader descriptions for tabs and badges . While optional, we strongly encourage their use.

Content descriptions

Adding a content description to the entire TabLayout can be done in XML with the android:contentDescription attribute or programmatically like so:

tabLayout.contentDescription = contentDescription

Content descriptions can also be added to individual tabs:

val tab = tabLayout.getTabAt(index)
tab?.contentDescription = contentDescription

BadgeDrawable also has a number of content description setters for different badge states:

val badge = tab.getOrCreateBadge()
badge.setContentDescriptionNumberless(contentDescription)
badge.setContentDescriptionQuantityStringsResource(R.string.content_description)
badge.setContentDescriptionExceedsMaxBadgeNumberStringResource(R.string.content_description)

Using tabs with ViewPager

A TabLayout can be setup with a ViewPager in order to:

  • Dynamically create TabItems based on the number of pages, their titles, etc.
  • Synchronize the selected tab and tab indicator position with page swipes

Firstly, your PagerAdapter (or subclass) needs to overrride the getPageTitle function in order to set the tab text label:

class Adapter : PagerAdapter() {

    ...

    override fun getPageTitle(position: Int): CharSequence? {
        // Return tab text label for position
    }
}

After the adapter has been set on the ViewPager, synchronize the TabLayout like so:

tabLayout.setupWithViewPager(viewPager)

Further customization of the dynamically-created TabItems (such as setting icons) needs to be done separately:

val tab = tabLayout.getTabAt(index)
tab?.icon = drawable

Using tabs with ViewPager2

Setting up a TabLayout with a ViewPager2 relies on the same concepts as doing so with a ViewPager, but the implementation is different. Everything is handled by the TabLayoutMediator class:

TabLayoutMediator(tabLayout, viewPager2) { tab, position ->
    when (position) {
        0 -> {
            tab.text = textLabel1
            tab.icon = drawable1
        }
        1 -> {
            tab.text = textLabel2
            tab.icon = drawable2
        }
        ...
    }
}.attach()

Adding badges to tabs

Example of 3 fixed tabs with badges: a red dot, a red badge with "1", and a red badge with "+999.

Tabs support badging with the BadgeDrawable class:

// Get badge from tab (or create one if none exists)
val badge = tab.getOrCreateBadge()
// Customize badge
badge.number = number
// Remove badge from tab
tab.removeBadge()

Fixed tabs

Fixed tabs display all tabs on one screen, with each tab at a fixed width. The width of each tab is determined by dividing the number of tabs by the screen width. They don’t scroll to reveal more tabs; the visible tab set represents the only tabs available.

Fixed tabs example

API and source code:

The following example shows a row of fixed tabs.

Example of 3 fixed tabs.

In the layout:

<com.google.android.material.tabs.TabLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:tabMode="fixed">

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_1"
        android:icon="@drawable/ic_favorite_24dp"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_2"
        android:icon="@drawable/ic_music_24dp"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_3"
        android:icon="@drawable/ic_search_24dp"
        />

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

Scrollable tabs

Scrollable tabs are displayed without fixed widths. They are scrollable, such that some tabs will remain off-screen until scrolled.

Scrollable tabs example

API and source code:

The following example shows a row of scrollable tabs.

Example of 4 scrollable tabs.

In the layout:

<com.google.android.material.tabs.TabLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:tabMode="scrollable"
    app:tabContentStart="56dp">

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_1"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_2"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_3"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_4"
        />

    <com.google.android.material.tabs.TabItem
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/tab_5"
        />

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

Anatomy and key properties

Tabs have a container and each tab item has an optional icon and text label. Tab items can be in an active or inactive state. The tab indicator is shown below the active tab item.

Tabs anatomy diagram

  1. Container
  2. Active icon (optional if there’s a label)
  3. Active text label (optional if there’s an icon)
  4. Active tab indicator
  5. Inactive icon (optional if there’s a label)
  6. Inactive text label (optional if there’s an icon)
  7. Tab item

Container attributes

  Attribute Related method(s) Default value
Color android:background setBackground
getBackground		 ?attr/colorSurface
Elevation android:elevation setElevation 0dp
Height N/A N/A 48dp (inline text) or 72dp (non-inline text and icon)
Tab mode tabMode setTabMode
getTabMode		 fixed

Tab item icon attributes

  Attribute Related method(s) Default value
Icon android:icon setIcon
getIcon		 null
Color tabIconTint setTabIconTint
setTabIconTintResource
getTabIconTint		 colorOnSurface at 60% opacity and colorPrimary (activated) (see all states)

Tab item text label attributes

  Attribute Related method(s) Default value
Text android:text setText
getText		 null
Color tabTextColor setTabTextColors
getTabTextColors		 colorOnSurface at 60% opacity and colorPrimary (activated) (see all states)
Typography tabTextAppearance N/A ?attr/textAppearanceButton
Inline label tabInlineLabel setInlineLabel
setInlineLabelResource
isInlineLabel		 false

Tab item container attributes

  Attribute Related method(s) Default value
Ripple color tabRippleColor setTabRippleColor
setTabRippleColorResource
getTabRippleColor		 colorOnSurface at 8% opacity and colorPrimary at 8% opacity (activated) (see all states)
Unbounded ripple tabUnboundedRipple setUnboundedRipple
setUnboundedRippleResource
hasUnboundedRipple		 true
Gravity tabGravity setTabGravity
getTabGravity		 fill
Min width tabMinWidth N/A 72dp (scrollable) or wrap_content
Max width tabMaxWidth N/A 264dp
Padding tabPaddingStart
tabPaddingEnd
tabPaddingTop
tabPaddingBottom
tabPadding		 N/A 12dp
12dp
0dp
0dp
0dp

Tab indicator attributes

  Attribute Related method(s) Default value
Color tabIndicatorColor setSelectedTabIndicatorColor colorPrimary
Drawable tabIndicator setSelectedTabIndicator
getSelectedTabIndicator		 mtrl_tabs_default_indicator
Height tabIndicatorHeight setSelectedTabIndicatorHeight 2dp
Full width tabIndicatorFullWidth setTabIndicatorFullWidth
isTabIndicatorFullWidth		 true
Gravity tabIndicatorGravity setSelectedTabIndicatorGravity
getTabIndicatorGravity		 bottom
Animation duration tabIndicatorAnimationDuration N/A 250

Styles

  Style
Default style Widget.MaterialComponents.TabLayout
Primary background color style Widget.MaterialComponents.TabLayout.Colored
Primary (light theme) or surface (dark theme)
background color style		 Widget.MaterialComponents.TabLayout.PrimarySurface

Default style theme attribute: ?attr/tabStyle

See the full list of styles and attrs.

Theming tabs

Tabs support Material Theming and can be customized in terms of color and typography.

Tabs theming example

API and source code:

The following example shows a row of scrollable tabs with Material Theming.

Example of 4 scrollable tabs with light pink background. The selected text is dark pink, the unselected text is gray.

Implementing tabs theming

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

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="colorPrimary">@color/shrine_pink_900</item>
    <item name="colorSurface">@color/shrine_pink_light</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="textAppearanceButton">@style/TextAppearance.App.Button</item>
</style>

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

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

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="tabStyle">@style/Widget.App.TabLayout</item>
</style>

<style name="Widget.App.TabLayout" parent="Widget.MaterialComponents.TabLayout">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.TabLayout</item>
    <item name="tabTextAppearance">@style/TextAppearance.App.Button</item>
</style>

<style name="ThemeOverlay.App.TabLayout" parent="">
    <item name="colorPrimary">@color/shrine_pink_900</item>
    <item name="colorSurface">@color/shrine_pink_light</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
</style>

or using the style in the layout (affects only these tabs):

<com.google.android.material.tabs.TabLayout
    ...
    style="@style/Widget.App.TabLayout"
    />