Material Theming refers to the customization of your Material Design app to better reflect your product’s brand.
Our approach to theming relies on the relationships between the following concepts:
Components are expected to provide public APIs for a variety of parameters. An example of a component is MDCButton.
The Container scheme represents configurable theming data that can be applied to components via theming extensions. A container scheme consists of one scheme for each of the Material Theming subsystem schemes, including: color, shape, and typography.
Theming extensions are component extensions that, when invoked with a default container scheme, will theme a component according to the Material Design guidelines. The extension will map each subsystem scheme's values to the component’s parameters.
By default, components have reasonable defaults for all of their customizable properties, e.g. backgroundColor or titleFont. Theming extensions are the recommended way to express your brand through Material Theming.
In order to use the components and subsystem schemes you'll need to add both the component and its related Theming extension as a dependency. Theming extensions, when available, always have a suffix of +Theming. For example, to add Buttons and its Theming extension:
pod 'MaterialComponents/Buttons' pod 'MaterialComponents/Buttons+Theming'
import MaterialComponents.MaterialButtons import MaterialComponents.MaterialButtons_Theming let containerScheme = MDCContainerScheme() let button = MDCButton() button.applyTextTheme(withScheme: containerScheme)
#import <MaterialComponents/MaterialButtons.h> #import <MaterialComponents/MaterialButtons+Theming.h> MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init]; MDCButton *button = [[MDCButton alloc] init]; [button applyTextThemeWithScheme:containerScheme];
import MaterialComponents.MaterialContainerScheme let containerScheme = MDCContainerScheme() // You can directly configure scheme properties: containerScheme.colorScheme.primaryColor = .red // Or assign a customized scheme instance: let shapeScheme = MDCShapeScheme() containerScheme.shapeScheme = shapeScheme
#import <MaterialComponents/MaterialContainerScheme.h> MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init]; // You can directly configure scheme properties containerScheme.colorScheme.primaryColor = UIColor.redColor; // Or assign a customized scheme instance: MDCShapeScheme *shapeScheme = [[MDCShapeScheme alloc] init]; containerScheme.shapeScheme = shapeScheme
The simplest solution to adopting container schemes and theming extensions is to create a singleton container scheme instance that is accessible throughout your app.
func globalContainerScheme() -> MDCContainerScheming { let containerScheme = MDCContainerScheme() // Customize containerScheme here... return containerScheme } // You can now access your global theme throughout your app: let containerScheme = globalContainerScheme()
id<MDCContainerScheming> GlobalContainerScheme(); id<MDCContainerScheming> GlobalContainerScheme() { MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init]; // Customize containerScheme here... return containerScheme; } // You can now access your global theme throughout your app: id<MDCContainerScheming> containerScheme = GlobalContainerScheme();
If you need to support different themes in different contexts then we recommend a dependency injection-based approach. In short form: each view controller is provided the container scheme it should theme itself with.
extension MyViewController { func applyTheme(with containerScheme: MDCContainerScheming) { // Apply the theme where applicable. } }
@interface MyViewController (Theming) - (void)applyThemeWithContainerScheme:(id<MDCContainerScheming>)containerScheme { // Apply the theme where applicable. }
This migration guide covers the typical migration path from Themer usage to Theming extensions. Themers will eventually be deprecated and deleted. Theming extensions are the recommended replacement.
Theming extensions are discussed in detail above. For more information about Themers see the section below.
In general, every component's Themer targets will gradually be replaced by a single Theming extension target. This includes:
Some components do not have a Theming extension yet. We are prioritizing the remaining Theming extensions through bug #7172.
When migrating from Themers to a Theming extension the first thing to understand is that a Theming extension will apply all of the Material Theming subsystems (Color, Typography, Shape) to a given component. If you were previously relying on the ability to apply only one subsystem (e.g. Color) to a component, please file a feature request with a code snippet of your existing use case.
The migration from a subsystem Themer to a Theming extension will involve the following steps:
When a component has a theming extension it will always be available as a Theming target alongside the component. For example:
In CocoaPods:
// Old pod 'MaterialComponents/TextFields' pod 'MaterialComponents/TextFields+ColorThemer' // New pod 'MaterialComponents/TextFields' pod 'MaterialComponents/TextFields+Theming'
In Bazel:
// Old deps = [ "//components/schemes/TextFields", "//components/schemes/TextFields:ColorThemer", ], // New deps = [ "//components/schemes/TextFields", "//components/schemes/TextFields:Theming", ],
Replace any Themer import with the component's Theming import:
// Old import MaterialComponents.MaterialTextFields_ColorThemer // New import MaterialComponents.MaterialTextFields_Theming
// Old #import <MaterialComponents/MaterialTextFields+ColorThemer.h> // New #import <MaterialComponents/MaterialTextFields+Theming.h>
Replace any Themer code with the equivalent use of a component‘s Theming extension. Each Themer’s equivalent Theming extension is described in the Themer's header documentation.
// Old let colorScheme = MDCSemanticColorScheme(defaults: .material201804) MDCFilledTextFieldColorThemer.applySemanticColorScheme(colorScheme, to: textField) // New let scheme = MDCContainerScheme() textField.applyTheme(withScheme: scheme)
// Old MDCSemanticColorScheme *colorScheme = [[MDCSemanticColorScheme alloc] initWithDefaults:MDCColorSchemeDefaultsMaterial201804]; [MDCFilledTextFieldColorThemer applySemanticColorScheme:colorScheme toTextInputControllerFilled:textFields]; // New MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init]; [textField applyThemeWithScheme:containerScheme];
If you made customizations to one of the subsystem schemes, you can now customize the container scheme‘s subsystem instances instead. If you are using a shared container scheme throughout your app then you’ll likely only need to make these customizations once.
// Old let colorScheme = MDCSemanticColorScheme(defaults: .material201804) colorScheme.primaryColor = .red // New let scheme = MDCContainerScheme() scheme.colorScheme.primaryColor = .red
// Old MDCSemanticColorScheme *colorScheme = [[MDCSemanticColorScheme alloc] initWithDefaults:MDCColorSchemeDefaultsMaterial201804]; colorScheme.primaryColor = UIColor.redColor; // New MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init]; containerScheme.colorScheme.primaryColor = UIColor.redColor;
Note These will soon be deprecated for Theming Extensions outlined above.
Our approach to theming relies on the relationships between the following concepts:
Components are expected to provide public APIs for a variety of parameters. An example of a component is MDCBottomNavigation.
Schemes represent a set of opinionated properties that are intended to be mapped to component parameters. There is a scheme for each Material Theming subsystem. For example, there is a scheme for the color, shape, and typography subsystems.
Themers are objects that, when invoked with a scheme, will theme a component according to the Material Design guidelines.
In order to use the components, themers and subsystem schemes you'll need to add the targets to your Podfile:
pod 'MaterialComponents/TextFields' pod 'MaterialComponents/TextFields+ColorThemer' pod 'MaterialComponents/schemes/Color'
import MaterialComponents.MaterialColorScheme let colorScheme = MDCSemanticColorScheme(defaults: .material201804) // Configure custom properties to match your brand colorScheme.backgroundColor = .lightGray
#import <MaterialComponents/MaterialColorScheme.h> MDCSemanticColorScheme *colorScheme = [[MDCSemanticColorScheme alloc] initWithDefaults:MDCColorSchemeDefaultsMaterial201804]; // Configure custom properties to match your brand colorScheme.backgroundColor = UIColor.lightGrayColor
import MaterialComponents.MaterialTextFields import MaterialComponents.MaterialTextFields_ColorThemer let colorScheme = MDCSemanticColorScheme(defaults: .material201804) let textField = MDCTextField() let controller = MDCTextInputControllerFilled(textInput:textField) MDCFilledTextFieldColorThemer.applySemanticColorScheme(colorScheme, to: controller)
#import <MaterialComponents/MaterialTextFields.h> #import <MaterialComponents/MaterialTextFields+ColorThemer.h> MDCSemanticColorScheme *colorScheme = [[MDCSemanticColorScheme alloc] initWithDefaults:MDCColorSchemeDefaultsMaterial201804]; MDCTextField *textField = [[MDCTextField alloc] init]; MDCTextInputControllerFilled *controller = [[MDCTextInputControllerFilled alloc] initWithTextInput:textField]; [MDCFilledTextFieldColorThemer applySemanticColorScheme:colorScheme toTextInputControllerFilled:controller];