# Tabs [Tabs](https://material.io/components/tabs/) organize content across different screens, data sets, and other interactions. ![Tab types](assets/tabs/tabs-types.png) ## Contents * [Using tabs](#using-sliders) * [Fixed tabs](#fixed-tabs) * [Scrollable tabs](#scrollable-tabs) * [Theming tabs](#theming-tabs) ## 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](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md) page. ### Basic usage ![Three fixed tabs with one tab selected.](assets/tabs/tabs_basic.png) A [`TabLayout`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabLayout.java) can be added to a layout like so: ```xml ... ``` [`TabItem`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabItem.java)s can then be added as children of the `TabLayout` and adjusted as needed: ```xml ... ``` Changes to tab selection can be observed like so: ```kt 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: ```kt tabLayout.contentDescription = contentDescription ``` Content descriptions can also be added to individual tabs: ```kt val tab = tabLayout.getTabAt(index) tab?.contentDescription = contentDescription ``` `BadgeDrawable` also has a number of content description setters for different badge states: ```kt 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`](https://developer.android.com/reference/kotlin/androidx/viewpager/widget/ViewPager) in order to: * Dynamically create `TabItem`s based on the number of pages, their titles, etc. * Synchronize the selected tab and tab indicator position with page swipes Firstly, your [`PagerAdapter`](https://developer.android.com/reference/androidx/viewpager/widget/PagerAdapter) (or subclass) needs to overrride the `getPageTitle` function in order to set the tab text label: ```kt 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: ```kt tabLayout.setupWithViewPager(viewPager) ``` Further customization of the dynamically-created `TabItem`s (such as setting icons) needs to be done separately: ```kt val tab = tabLayout.getTabAt(index) tab?.icon = drawable ``` ### Using tabs with ViewPager2 Setting up a `TabLayout` with a [`ViewPager2`](https://developer.android.com/reference/androidx/viewpager2/widget/ViewPager2) relies on the same concepts as doing so with a `ViewPager`, but the implementation is different. Everything is handled by the [`TabLayoutMediator`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabLayoutMediator.java) class: ```kt 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.](assets/tabs/tabs_badged.png) Tabs support badging with the [`BadgeDrawable`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/badge/BadgeDrawable.java) class: ```kt // 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: * `TabLayout` * [Class definition](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout) * [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabLayout.java) * `TabItem` * [Class definition](https://developer.android.com/reference/com/google/android/material/tabs/TabItem) * [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabItem.java) The following example shows a row of fixed tabs. ![Example of 3 fixed tabs.](assets/tabs/tabs_fixed.png) In the layout: ```xml ``` ## 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: * `TabLayout` * [Class definition](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout) * [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabLayout.java) * `TabItem` * [Class definition](https://developer.android.com/reference/com/google/android/material/tabs/TabItem) * [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabItem.java) The following example shows a row of scrollable tabs. ![Example of 4 scrollable tabs.](assets/tabs/tabs_scrollable.png) In the layout: ```xml ``` ## 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](assets/tabs/tabs-anatomy.png) 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](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/res/color/mtrl_tabs_icon_color_selector.xml)) ### 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](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/res/color/mtrl_tabs_icon_color_selector.xml)) **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](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/res/color/mtrl_tabs_ripple_color.xml)) **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`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/res/drawable/mtrl_tabs_default_indicator.xml) **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](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/res/values/styles.xml) and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/res/values/attrs.xml). ## Theming tabs Tabs support [Material Theming](https://material.io/components/app-bars-bottom/#theming) and can be customized in terms of color and typography. ### Tabs theming example API and source code: * `TabLayout` * [Class definition](https://developer.android.com/reference/com/google/android/material/tabs/TabLayout) * [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabLayout.java) * `TabItem` * [Class definition](https://developer.android.com/reference/com/google/android/material/tabs/TabItem) * [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/tabs/TabItem.java) 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.](assets/tabs/tabs_theming.png) #### Implementing tabs theming Using theme attributes and styles in `res/values/styles.xml` (themes all tabs and affects other components): ```xml ``` or using default style theme attributes, styles and theme overlays (themes all tabs but does not affect other components): ```xml ``` or using the style in the layout (affects only these tabs): ```xml ```