Share via

Apply report themes

  • Article

Power BI report themes allow you to apply design changes to your entire report. For example, you can include your corporate colors, and change your icon sets. When you apply a report theme, all visuals in your report use the colors and formatting from your selected theme as their defaults. For more information about theme settings and how they're designed, see Report theme JSON file format.

You can save and publish a report with a theme applied to it. The applied theme is the default theme for this report when it's loaded in Power BI Service or Power BI embedded analytics.

Developers using Power BI embedded analytics also have the ability to embed a report with a custom theme applied instead of the default theme for the report. Applying a theme this way loads the same report with different themes to different users according to their settings.

Report theme object

This section describes the report theme object that is used to represent themes. An IReportTheme object type can be passed to the embedded configuration.

interface IEmbedConfiguration extends IEmbedConfigurationBase {
  ...
  theme?: models.IReportTheme;
}

The report theme object should have a single parameter named themeJson. This field should contain the JSON object that represents the theme settings. For more information, see the Report theme JSON file format page.

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

Apply a theme to a report

The applied theme can also be changed after the report is loaded. When you apply the theme after the report loads, the end-user can select a theme from a list and see the style changes applied to the report immediately without reloading.

Apply a theme on load

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

// Parse the theme JSON file into an object
let themeJsonObject = parseJsonfile(path);
let embedConfig = {
    …
    theme: {
        themeJson: themeJsonObject
    }
};

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

Apply theme in run time

The apply method is useful if you want to change the theme after the report is loaded without reloading the report.

The Power BI Client Report class defines the applyTheme method as:

applyTheme(theme: models.IReportTheme): Promise<void>

The applyTheme API changes the theme that is applied to the report in run time.

...
// Parse the theme JSON file into an object
let themeJsonObject = parseJsonfile(path); 

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

Apply a theme when you create a report

A new embedded report can be created with a theme applied to it. New visuals added to the report respect the theme style. See also the Create, edit, and save an embedded report page.

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

// Parse the theme JSON file into an object
let themeJsonObject  = parseJsonfile(path);
let embedCreateConfiguration = {
  …
  theme: {
    themeJson: themeJsonObject 
  }
};

let report = powerbi.createReport(embedContainer, embedCreateConfiguration);

Note

parseJsonfile is a function that needs to be implemented on the application code and isn't part of the SDK.

Reset a report theme

The reset method is useful if you want to reset the report theme to the default theme but you don't have the theme JSON file.

The Power BI Client Report class defines the resetTheme method as:

resetTheme(): Promise<void>

Calling the resetTheme API returns to the default theme of the report.

// Apply the theme
report.resetTheme();

Considerations and limitations

  • Using the applyTheme API described above overrides the default theme entirely with the new JSON file. The API won't extend the configuration of the default theme.
  • There are a few times when applying themes doesn't change the visuals in the report like you're expecting. For more information, see Situations when Report Theme colors don't stick to your reports.
  • You can't use the API to apply a theme and set a contrast level at the same time. If you configure both properties, the API uses the contrast level that you specified but ignores the theme setting.

Related content