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:

  1. Components
  2. The Container Scheme
  3. Theming Extensions

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.

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:

Schemes

Examples

How to theme a component with a container scheme

Swift

Objective-C

How to customize a container scheme

Swift

Objective-C

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

Objective-C

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.

Swift

Objective-C

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 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:

  • 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 bug #7172.

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 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:

  1. Update your dependencies.
  2. Update your imports.
  3. 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:

In Bazel:

Update your imports

Replace any Themer import with the component's Theming import:

Swift

Objective-C

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

Objective-C

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

Objective-C

Themers

Note These will soon be deprecated for Theming Extensions outlined above.

Our approach to theming relies on the relationships between the following concepts:

  1. Components
  2. Schemes
  3. Themers

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.

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:

Using a scheme

Swift

Objective-C

Examples

Swift

Objective-C

Up next