Apply Report Themes

Background

Power BI gives the ability to apply a style theme to your entire report, such as corporate colors, seasonal coloring, or other custom styles. When you apply a Report Theme, all visuals in your report use the style from your selected theme. You will find additional information about the feature in this document: Use Report Themes in Power BI Desktop. The theme settings should be defined in a JSON file in a format described in this section: 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 or Power BI embedded analytics.

Developers using Power BI embedded analytics have 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 style. See also the 'Create Report Embed View' page.

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 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();

4. Apply theme on create report

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

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

Limitations & considerations

• Using the applyTheme API described above, will override the actual theme entirely with the new JSON file, it will not extend the configuration of the actual theme.
• A few exceptions apply on theme style applying, and they are described in this article: Situations when Report Theme colors won't stick to your reports