Customize report colors and mode showcase
The Power BI embedded theme API defines and applies color palettes and other styles to Power BI reports. Use the themes feature to apply customized themes for different report users, or to let users choose their own look and feel.
The Customize report colors and mode showcase in the Power BI embedded analytics playground uses the theme API to let users choose different colors and background modes when viewing a Power BI embedded analytics report.
The showcase report uses the theme feature to:
- Define report color themes and background modes.
- Apply a specific color theme on report load.
- Let users change themes and background modes during their report viewing sessions.
For more information about report themes, see Use report themes in Power BI Desktop.
Theme showcase experience
In the Customize report colors and mode showcase, an imaginary conglomerate named Contoso uses a Power BI embedded report to show business data to their stakeholders. The embedded report loads with the Default color theme and default background mode applied. All visuals in the report use the theme colors.
Select a theme and mode
Report viewers can select the Choose theme button to apply a different color theme or mode. The Choose theme drop-down box opens, listing the available theme names and color palettes, with the current theme selected.
Viewers can select a different theme from the list and see the immediate changes in data, label, and other element colors. The selected theme affects all the embedded visuals in the report.
Viewers can also toggle Dark mode to produce a dark report background with light-colored text, independent of the color theme selection.
Selecting Choose theme again closes the drop-down box. The new selected theme and background mode remain in effect during the report viewing session, unless the viewer changes them again.
Theme showcase code
The code for implementing the showcase application is in the PowerBI-Embedded-Showcases GitHub repository.
The HTML page builds the report container and Choose theme button and dialog box, and loads the themes JSON objects.
The report JavaScript embeds the report, loads the default theme, and implements the theme switching experience.
Define themes with report theme JSON objects
You can customize almost all Power BI formatting elements through report theme JSON objects. The showcase themes.js file defines jsonDataColors
objects that specify available color theme names and properties.
The following jsonDataColors
object defines the showcase Tidal
theme. The asterisk *
applies a setting globally to all the visuals in the report.
const jsonDataColors = [
...
{
"name": "Tidal",
"dataColors": ["#094782", "#0B72D7", "#098BF5", "#54B5FB", "#71C0A7", "#57B956", "#478F48", "#326633"],
"tableAccent": "#094782",
"visualStyles": {
"*": {
"*": {
"background": [{ "show": true, "transparency": 3 }],
"visualHeader": [{
"foreground": { "solid": { "color": "#094782" } },
"transparency": 3
}]
}
},
"group": { "*": { "background": [{ "show": false }] } },
"basicShape": { "*": { "background": [{ "show": false }] } },
"image": { "*": { "background": [{ "show": false }] } },
"page": {
"*": {
"background": [{ "transparency": 100 }],
}
}
}
}
...
]
For more information about report theme JSON object file format and properties, see Report theme JSON file format.
Define background modes
The themes.js file also defines themes
objects that describe the Light and Dark background modes. To define Light and Dark background modes, the themes
object specifies one theme with a white background, and another theme with a contrasting, dark-colored background. The dark-background object also sets the values for other structural and text colors so they're visible against the dark background.
Apply themes with embed configuration and applyTheme
The showcase themeJson
parameter defines several color themes. The embedded report JavaScript uses the Report class applyTheme method to apply themes on report load and during report runtime.
To enable themes, the report embed configuration specifies a theme
attribute, with a themeJson
parameter pointing to the themes JSON object. The showcase embed configuration applies the Default
theme, which has data-color ID 0
, on report load:
let config = {
...
theme: { themeJson: jsonDataColors[0] },
};
If the viewer selects a different theme or mode during their session, the applyTheme function defines and applies a new theme object based on the selected data color and mode. The following code shows the showcase applyTheme
function:
async function applyTheme() {
// Get active data-color ID
activeDataColorId = Number($("input[name=data-color]:checked", "#theme-dropdown")[0].getAttribute("id").slice(-1));
// Get the theme state from the slider toggle
let activeThemeSlider = $("#theme-slider").get(0);
// Get the index of the theme based on the state of the slider
// 1 => Dark theme
// 0 => Light theme
const themeId = (activeThemeSlider.checked) ? 1 : 0;
// Create new theme object
let newTheme = {};
// Append the data colors and the mode
$.extend(newTheme, jsonDataColors[activeDataColorId], themes[themeId]);
// Apply the theme to the report
await themesShowcaseState.themesReport.applyTheme({ themeJson: newTheme });
}