A banner displays a prominent message and related optional actions.
Contents
Add the following to your Podfile
:
pod 'MaterialComponents/Banner'
Then, run the following command:
pod install
To use the MDCBannerView
in your code, import the MaterialBanner umbrella header (Objective-C) or MaterialComponents module (Swift).
import MaterialComponents.MaterialBanner
#import "MaterialBanner.h"
The system will set accessibilityLabel
for the elements in the banner that contain text. As always, you are free to change these labels if it leads to a better VoiceOver expoerience. Consider setting an accessibilityLabel
on the image view.
The only non-standard accessibiility API exposed on MDCBannerView
is mdc_adjustsFontForContentSizeCategory
, which is an alternative to adjustsFontForContentSizeCategory
that is specific to the MDC iOS library. Eventually we will deprecate and delete mdc_adjustsFontForContentSizeCategory
.
On iOS there is just one type of banner.
A banner displays an important, succinct message, and provides actions for users to address (or dismiss the banner). It requires a user action to be dismissed.
Banners should be displayed at the top of the screen, below a top app bar. They’re persistent and nonmodal, allowing the user to either ignore them or interact with them at any time. Only one banner should be shown at a time.
By default, MDCBannerView
is configured to display an image view, a text label and two buttons. To hide the image view on MDCBannerView
, users can set the hidden
property on imageView
to be true. Similarly, users can hide a button on the banner view by setting the hidden
property on trailingButton
to be true.
By default, MDCBannerView
is configured to display items with black text and white background with a grey divider at the bottom of the view. To customize the color and style of the text, image view and buttons displayed on MDCBannerView
, directly set the relevant properties, such as tintColor
, on textView
, imageView
, leadingButton
and trailingButton
. showsDivider
and dividerColor
can be used to control the divider's visibility and color.
MDCBannerView
layouts are configurable through the bannerViewLayoutStyle
property. This property can be set to either MDCBannerViewLayoutStyleAutomatic
, MDCBannerViewLayoutStyleSingleRow
, MDCBannerViewLayoutStyleMultiRowStackedButton
, or MDCBannerViewLayoutStyleMultiRowAlignedButton
.
MDCBannerView
uses layoutMargins
to manage the margins for elements on the banner view.
The following is a typical setup for an MDCBannerView
.
let bannerView = MDCBannerView() bannerView.textView.text = "Banner text" bannerView.mdc_adjustsFontForContentSizeCategory = true let button = bannerView.leadingButton button.setTitle("Dismiss", for: .normal) bannerView.trailingButton.hidden = true bannerView.imageView.hidden = true bannerView.showsDivider = true addSubview(bannerView)
MDCBannerView *bannerView = [[MDCBannerView alloc] init]; bannerView.textView.text = @"Banner text"; bannerView.mdc_adjustsFontForContentSizeCategory = YES; MDCButton *button = bannerView.leadingButton; [button setTitle:@"Dismiss" forState:UIControlStateNormal]; bannerView.trailingButton.hidden = YES; bannerView.imageView.hidden = YES; bannerView.showsDivider = YES; [self addBannerView:bannerView];
Banners consist of the following:
Attribute | Related method(s) | Default value | |
---|---|---|---|
Image view | imageView | -[MDCBannerView imageView] | N/A |
Image | imageView.image | -[UIImageview setImage:] -[UIImageview image] | N/A |
Attribute | Related method(s) | Default value | |
---|---|---|---|
Color | backgroundColor | -[MDCBannerView setBackgroundColor:] -[MDCBannerView backgroundColor] | White |
Attribute | Related method(s) | Default value | |
---|---|---|---|
Text | textView.text | -[UITextView setText:] -[UITextView text] | nil |
Color | textView.text | -[UITextView setTextColor:] -[UITextView textColor] | Black |
Typography | textView.font | -[UITextView setFont:] -[UITextView font] | Body 2 font |
Attribute | Related method(s) | Default value | |
---|---|---|---|
Leading button | leadingButton | -[MDCBannerVieiw leadingButton] | N/A |
Trailing button | trailingButton | -[MDCBannerVieiw trailingButton] | N/A |
MDCBannerView
supports Material Theming using a container scheme.
Here is an example of a Banner with the Shrine theme applied to it.
To theme your banner, first add the following to your Podfile
:
pod 'MaterialComponents/Banner+Theming'
Then run the installer:
pod install
From there, import the relevant target or file and call the theming method.
// Import the Banner theming module import MaterialComponents.MaterialBanner_Theming ... // Create or use your app's Container Scheme let containerScheme = MDCContainerScheme() // Theme the banner with either default theme banner.applyTheme(withScheme: containerScheme)
// Import the Banner Theming Extensions header #import <MaterialComponents/MaterialBanner+Theming.h> ... // Create or use your app's Container Scheme MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init]; // Theme the banner with either default theme [self.bannerView applyThemeWithScheme:containerScheme];