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

Next steps

• Apply report themes
• Power BI Embedded Analytics Playground