Theming
Material Theming refers to the customization of your Material Design app to better reflect your product’s brand.
Theming extensions
Terminology
Our approach to theming relies on the relationships between the following concepts:
- Components
- The Container Scheme
- Theming Extensions
Components are expected to provide public APIs for a variety of parameters. An example of a component is
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
Sensible defaults, yet highly configurable
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.
How to get the code
Cocoapods
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'
Schemes
Examples
How to theme a component with a container scheme
Swift
import MaterialComponents.MaterialButtons
import MaterialComponents.MaterialButtons_Theming
let containerScheme = MDCContainerScheme()
let button = MDCButton()
button.applyTextTheme(withScheme: containerScheme)
Objective-C
xxxxxxxxxx
How to customize a container scheme
Swift
xxxxxxxxxx
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
Objective-C
xxxxxxxxxx
Recommended theming patterns
The simplest solution to adopting container schemes and theming extensions is to create a singleton container scheme instance that is accessible throughout your app.
Swift
xxxxxxxxxx
func globalContainerScheme() -> MDCContainerScheming {
let containerScheme = MDCContainerScheme()
// Customize containerScheme here...
return containerScheme
}
// You can now access your global theme throughout your app:
let containerScheme = globalContainerScheme()
Objective-C
xxxxxxxxxx
If you need to support different themes in different contexts then we recommend a
Swift
xxxxxxxxxx
extension MyViewController {
func applyTheme(with containerScheme: MDCContainerScheming) {
// Apply the theme where applicable.
}
}
Objective-C
xxxxxxxxxx
Migration guide: themers to theming extensions
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
In general, every component's Themer targets will gradually be replaced by a single Theming extension target. This includes:
- ColorThemer
- FontThemer
- ShapeThemer
- TypographyThemer
- Component Themers (e.g. CardThemer)
Some components do not have a Theming extension yet. We are prioritizing the remaining Theming
extensions through
Typical migration
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
The migration from a subsystem Themer to a Theming extension will involve the following steps:
- Update your dependencies.
- Update your imports.
- Make changes to your code.
Update your dependencies
When a component has a theming extension it will always be available as a Theming target alongside the component. For example:
In CocoaPods:
xxxxxxxxxx
// Old
pod 'MaterialComponents/TextFields'
pod 'MaterialComponents/TextFields+ColorThemer'
// New
pod 'MaterialComponents/TextFields'
pod 'MaterialComponents/TextFields+Theming'
In Bazel:
xxxxxxxxxx
// Old
deps = [
"//components/schemes/TextFields",
"//components/schemes/TextFields:ColorThemer",
],
// New
deps = [
"//components/schemes/TextFields",
"//components/schemes/TextFields:Theming",
],
Update your imports
Replace any Themer import with the component's Theming import:
Swift
xxxxxxxxxx
// Old
import MaterialComponents.MaterialTextFields_ColorThemer
// New
import MaterialComponents.MaterialTextFields_Theming
Objective-C
xxxxxxxxxx
Make changes to your code
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.
Swift
xxxxxxxxxx
// Old
let colorScheme = MDCSemanticColorScheme(defaults: .material201804)
MDCFilledTextFieldColorThemer.applySemanticColorScheme(colorScheme, to: textField)
// New
let scheme = MDCContainerScheme()
textField.applyTheme(withScheme: scheme)
Objective-C
xxxxxxxxxx
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.
Swift
xxxxxxxxxx
// Old
let colorScheme = MDCSemanticColorScheme(defaults: .material201804)
colorScheme.primaryColor = .red
// New
let scheme = MDCContainerScheme()
scheme.colorScheme.primaryColor = .red
Objective-C
xxxxxxxxxx
Themers
Note These will soon be deprecated for Theming Extensions outlined above.
Our approach to theming relies on the relationships between the following concepts:
- Components
- Schemes
- Themers
Components are expected to provide public APIs for a variety of parameters. An example of a component is
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
How to get the code
Cocoapods
In order to use the components, themers and subsystem schemes you'll need to add the targets to your Podfile:
xxxxxxxxxx
pod 'MaterialComponents/TextFields'
pod 'MaterialComponents/TextFields+ColorThemer'
pod 'MaterialComponents/schemes/Color'
Using a scheme
Swift
xxxxxxxxxx
import MaterialComponents.MaterialColorScheme
let colorScheme = MDCSemanticColorScheme(defaults: .material201804)
// Configure custom properties to match your brand
colorScheme.backgroundColor = .lightGray
Objective-C
xxxxxxxxxx
Examples
Swift
xxxxxxxxxx
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)
Objective-C
xxxxxxxxxx