README.md

Tabs

Tabs are bars of buttons used to navigate between groups of content.

Design & API documentation

• Material Design guidelines: Tabs
• Class: MDCTabBarUnderlineIndicatorTemplate
• Class: MDCTabBar
• Class: MDCTabBarIndicatorAttributes
• Class: MDCTabBarViewController
• Protocol: MDCTabBarControllerDelegate
• Protocol: MDCTabBarDelegate
• Protocol: MDCTabBarIndicatorContext
• Protocol: MDCTabBarIndicatorTemplate
• Enumeration: Enumerations
• Enumeration: MDCTabBarAlignment
• Enumeration: MDCTabBarItemAppearance
• Enumeration: MDCTabBarItemState
• Enumeration: MDCTabBarTextTransform

Table of contents

• Overview
• Installation
  • Installation with CocoaPods
  • Importing
• Usage
  • Importing
  • Delegate
  • Selected item
  • Appearance
  • Styling
  • Custom selection indicators
  • Bottom navigation
• Examples
  • Creating a tab bar
• Extensions
  • Color Theming
  • Typography Theming
  • Theming Extensions
• MDCTabBarView
  • Importing MDCTabBarView
  • Typical Use of MDCTabBarView
  • Migrating from MDCTabBar

---

Overview

When a user taps a tab, the content changes to match the selected subject in the tabs.

We provide this functionality through MDCTabBar which communicates via a delegate as well as MDCTabBarViewController which provides a view containment model similar to UITabViewController.

Tabs can also show a badge (usually a number) like UITabBar.

Installation

Installation with CocoaPods

Add the following to your Podfile:

pod 'MaterialComponents/Tabs'

Then, run the following command:

pod install

Importing

To import the component:

Swift

import MaterialComponents.MaterialTabs

Objective-C

#import "MaterialTabs.h"

Usage

Importing

To use the tab bar in your code, import the MaterialTabs umbrella header (Objective-C) or MaterialComponents module (Swift).

Swift

import MaterialComponents

Objective-C

#import "MaterialTabs.h"

Delegate

Conform your class to the MDCTabBarDelegate protocol and set it as the tab bar's delegate to handle updating the UI when the user selects a tab.

Selected item

Update the selected tab programmatically by setting selectedItem, optionally with an animation. Delegate methods are not called for programmatic changes, so callers are responsible for updating UI as needed after updating the selected item.

Appearance

Set the itemAppearance property on the tab bar to switch between item display modes. Items can be displayed as titles (the default), icons, or combined.

Styling

By default, the tab bar is configured to display items with white text and icons. To customize the color of the tab bar, set the tintColor, selectedItemTintColor, unselectedItemTintColor, inkColor, and barTintColor properties. If selectedItemTintColor is nil, the tab bar's tintColor will be used automatically for selected items.

Configure where items are placed in the tab bar by setting the alignment property.

Custom selection indicators

The currently-selected tab is indicated visually by a selection indicator. By default this is an underline, but you can customize its appearance by defining a selection indicator template and setting the selectionIndicatorTemplate property on the tab bar. Template objects are provided contextual information about a tab's content and return attributes that describe how that tab's indicator should appear. The indicator will then automatically display the provided shape and animate changes as the user selects different tabs.

See MDCTabBarIndicatorTemplate and MDCTabBarIndicatorAttributes for details.

Bottom navigation

Implement positionForBar: and return UIBarPositionBottom to configure the tab bar as a bottom navigation bar. The bar will automatically update with the appropriate styling.

Examples

Creating a tab bar

Swift

let tabBar = MDCTabBar(frame: view.bounds)
tabBar.items = [
UITabBarItem(title: "Recents", image: UIImage(named: "phone"), tag: 0),
UITabBarItem(title: "Favorites", image: UIImage(named: "heart"), tag: 0),
]
tabBar.itemAppearance = .titledImages
tabBar.autoresizingMask = [.flexibleWidth, .flexibleBottomMargin]
tabBar.sizeToFit()
view.addSubview(tabBar)

Objective-C

MDCTabBar *tabBar = [[MDCTabBar alloc] initWithFrame:self.view.bounds];
tabBar.items = @[
    [[UITabBarItem alloc] initWithTitle:@"Recents" image:[UIImage imageNamed:@"phone"] tag:0],
    [[UITabBarItem alloc] initWithTitle:@"Favorites" image:[UIImage imageNamed:@"heart"] tag:0],
];
tabBar.itemAppearance = MDCTabBarItemAppearanceTitledImages;
tabBar.autoresizingMask =
    UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleBottomMargin;
[tabBar sizeToFit];
[self.view addSubview:tabBar];

Extensions

Color Theming

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

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

pod 'MaterialComponents/Tabs+ColorThemer'

Swift

// Step 1: Import the ColorThemer extension
import MaterialComponents.MaterialTabs_ColorThemer

// Step 2: Create or get a color scheme
let colorScheme = MDCSemanticColorScheme()

// Step 3: Apply the color scheme to your component
// Primary variant
MDCTabBarColorThemer.applySemanticColorScheme(colorScheme, toTabs: component)
// Or surface variant
MDCTabBarColorThemer.applySurfaceVariant(withColorScheme: colorScheme, toTabs: component)

Objective-C

// Step 1: Import the ColorThemer extension
#import "MaterialTabs+ColorThemer.h"

// Step 2: Create or get a color scheme
id<MDCColorScheming> colorScheme = [[MDCSemanticColorScheme alloc] initWithDefaults:MDCColorSchemeDefaultsMaterial201804];

// Step 3: Apply the color scheme to your component
// Primary variant
[MDCTabBarColorThemer applySemanticColorScheme:colorScheme toTabs:component];
// Or surface variant
[MDCTabBarColorThemer applySurfaceVariantWithColorScheme:colorScheme toTabs:component];

Typography Theming

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

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

pod 'MaterialComponents/Tabs+TypographyThemer'

Swift

// Step 1: Import the TypographyThemer extension
import MaterialComponents.MaterialTabs_TypographyThemer

// Step 2: Create or get a typography scheme
let typographyScheme = MDCTypographyScheme()

// Step 3: Apply the typography scheme to your component
MDCTabBarTypographyThemer.applyTypographyScheme(typographyScheme, to: component)

Objective-C

// Step 1: Import the TypographyThemer extension
#import "MaterialTabs+TypographyThemer.h"

// Step 2: Create or get a typography scheme
id<MDCTypographyScheming> typographyScheme = [[MDCTypographyScheme alloc] init];

// Step 3: Apply the typography scheme to your component
[MDCTabBarTypographyThemer applyTypographyScheme:colorScheme
     toTabBar:component];

Theming Extensions

MDCTabBar supports Material Theming using a Container Scheme. There are two variants for Material Theming of a MDCTabBar, which are the Primary Theme and the Surface Theme.

Swift

// Import the Tabs Theming Extensions module
import MaterialComponents.MaterialTabs_MaterialTheming
 ...
 // Create or use your app's Container Scheme
let containerScheme = MDCContainerScheme()
 // Theme the tab bar with either Primary Theme
tabBar.applyPrimaryTheme(withScheme: containerScheme)
 // Or Surface Theme
tabBar.applySurfaceTheme(withScheme: containerScheme)

Objective-C

// Import the Tabs Theming Extensions header
#import <MaterialComponents/MaterialTabBar+MaterialTheming.h>
 ...
 // Create or use your app's Container Scheme
MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init];
 // Theme the tab bar with either Primary Theme
[self.tabBar applyPrimaryThemeWithScheme:containerScheme];
 // Or Surface Theme
[self.tabBar applySurfaceThemeWithScheme:containerScheme];

MDCTabBarView

NOTE: This is currently in Beta. Features may change without warning and without a change in the Material Components for iOS version number.

Importing MDCTabBarView

MDCTabBarView is currently part of the MaterialComponentsBeta podspec. You may need to follow the Material Components for iOS Beta integration guide to configure your project to use MDCTabBarView.

Swift

import MaterialComponentsBeta.MaterialTabs_TabBarView

Objective-C

#import "MaterialTabs+TabBarView.h"

Typical Use of MDCTabBarView

Swift

let tabBarView = MDCTabBarView()
addSubview(tabBarView)

// Configure constraints

Objective-C

MDCTabBarView *tabBarView = [[MDCTabBarView alloc] init];
[self.view addSubview:tabBarView];

// Configure constraints

Migrating from MDCTabBar

Subclassing Restricted

Subclassing is not supported by MDCTabBarView. Any requirements that you have for Material Tabs that are not met by the public APIs should be filed as a feature request or bug against MDCTabBarView.

Selected Item Behavior

MDCTabBarView does not automatically mark any item as selected when the items array is set, unless the previously-selected item is in the new items array. This is a change from MDCTabBar, but ensures that the view and its APIs present equivalent information.

Colors, Fonts, and Theming

To set the image tint colors, use - setImageTintColor:forState:. The MDCTabBar APIs, - selectedItemTintColor and - unselectedItemTintColor are unavailable.

To set the fonts of the labels, use - setTitleFont:forState:. The MDCTabBar APIs, - selectedItemTitleFont and - unselectedItemTitleFont are unavailable. Note that the tab bar may adjust the sizes of its views to account for changes in fonts, and that can result in unexpected changes from Fixed Tabs to Scrollable Tabs depending on font choices and title length.

MDCTabBarView uses Material Ripple by default (MDCRippleView) and does not support Ink. You may configure the Ripple color for touch feedback by setting the - rippleColor property.

Alignment and Item Rendering

The MDCTabBar API itemAppearance has no equivalent on MDCTabBarView. Whatever relevant properties (e.g., title, image) are provided on UITabBarItem should be used instead.

The MDCTabBar APIs displaysUppercaseTitles and titleTextTransform have no equivalent in MDCTabBarView. Titles are rendered as set on UITabBarItem and accessibilityLabel should be set on the item if the title text is not correctly handled by UIAccessibility.

UIBarPositioningDelegate

MDCTabBarView no longer conforms to UIBarPositioning, since Material Tabs are always positioned above their related content views. As a result, MDCTabBarViewDelegate does not inherit from UIBarPositioningDelegate.

Selection Indicator Template

The Selection Indicator Template APIs and protocols are copied nearly verbatim from MDCTabBar, with the names changed to prevent collision. One difference is the expected behavior of contentFrame as used by the indicator template. In MDCTabBar the value of contentFrame was the union of the title and image frames. However, in MDCTabBarView the width of the contentFrame is always the width of the title (when present), and the height will include both the title and image. This change is necessary to support internal clients.

Custom Views

Features like badges and horizontal layout of titles and images are not supported on MDCTabBarView. Clients who need such behavior should implement their own custom UIView and assign it to the mdc_customView property of a UITabBarItem sublcass that conforms to MDCTabBarItemCustomViewing. A simple subclass conforming to the MDCTabBarItemCustomViewing protocol is provided as MDCTabBarItem.

Swift

let customView = MyCustomTabView()
let customItem = MDCTabBarItem()
customItem.mdc_customView = customView
let tabBarView = MDCTabBarView()
tabBarView.items = [ customItem ]

Objective-C

MyCustomTabView *customView = [[MyCustomTabView alloc] init];
MDCTabBarItem *customItem = [[MDCTabBarItem alloc] init];
customItem.mdc_customView = customView;
MDCTabBarView *tabBarView = [[MDCTabBarView alloc] init];
tabBarView.items = @[ customItem ]

NOTE: This will be updated as APIs are added and migrations are defined.