Apply Report Themes

Apply Report Themes

Background

Power BI gives the ability to apply a color theme to your entire report, such as corporate colors, seasonal coloring, or other color themes. When you apply a Report Theme, all visuals in your report use the colors from your selected theme. You will find additional information about the feature in this document: https://docs.microsoft.com/en-us/power-bi/desktop-report-themes The theme settings should be defined in a JSON file in a format described in this section: https://docs.microsoft.com/en-us/power-bi/desktop-report-themes#report-theme-json-file-format

Functionality

A report can be saved and published with a theme applied on it and this will be the default theme for this report when it will be loaded in Power BI Service and Power BI Embedded.

Developers using Power BI Embedded had also the ability to embed a report with a custom theme applied instead of the default theme of the report. It allows for example to load the same report with different themes to different users according to their settings.

The applied theme can also be changed after the report is loaded, to support scenarios where the end-user selects a theme from a list and see the style changes applied to the report immediately without reloading.

Finally a new embedded report can be created with a theme applied on it. New visuals added to the report will respect the theme colors. See also the 'Create Report in Embed View' page: https://github.com/Microsoft/PowerBI-JavaScript/wiki/Create-Report-in-Embed-View

Interfaces and APIs

An object of type IReportTheme can be passed to the embedded configuration or to the applyTheme API to support the scenarios mentioned above. This object should have a single parameter name themeJson with any type. This field should contains the object read from the JSON file containing the themes settings (See https://docs.microsoft.com/en-us/power-bi/desktop-report-themes#report-theme-json-file-format) Calling the resetTheme API returns to the default theme of the report.

/**
 * Configuration settings for Power BI embed components
 *
 * @export
 * @interface IEmbedConfiguration
 */
export interface IEmbedConfiguration extends IEmbedConfigurationBase {
  ...
  theme?: models.IReportTheme;
}

/*
 * Report Theme
 */

export interface IReportTheme {}
export interface ICustomTheme extends IReportTheme {
  themeJson: any;
}

/**
  * Apply a theme to the report
  *
  * report.applyTheme(theme);
  */
applyTheme(theme: models.IReportTheme): Promise<void>;

/**
* Reset and apply the default theme of the report
*
* report.resetDefaultTheme();
*/
resetDefaultTheme(): Promise<void>;

Examples

1. Apply theme on load

This is useful if you want to apply a custom theme on report load.

// parse the theme JSON file into an object
var themeJson = parseJsonfile(path); 
var embedConfig = {
    …
    theme: {themeJson: themeJson}
};
…
var report = powerbi.embed(embedContainer, embedConfig);

2. change theme after load

This is useful if you want to change the theme after the report is loaded without reloading the report.

...
var report = powerbi.embed(embedContainer, embedConfig);
...
// parse the theme JSON file into an object
var themeJson = parseJsonfile(path); 

// apply the theme
report.applyTheme({themeJson:themeJson});

3. Reset to default theme

This is useful if you want to reset the default theme defined on the report but you don't have the theme JSON file.

...
var report = powerbi.embed(embedContainer, embedConfig);
...

// apply the theme
report.resetTheme();

Limitations & considerations

A few exceptions apply on theme style applying, and they are described in this article. https://docs.microsoft.com/en-us/power-bi/desktop-report-themes#situations-when-report-theme-colors-wont-stick-to-your-reports