Power BI reports that you embed in apps contain visuals, such as charts, heat maps, and gauges. These visuals have headers that make actions available to users. When you use Power BI, you can hide or show the header of each visual in a report. Each visual has a card in theFormatting section of theVisualizations pane calledVisual header. You can use that card to turn the visual's header on and off. Learn more about visual headers inVisual headers.

Examples of actions in visual headers include:

• Opening the visual in focus mode.
• Drilling down or up.
• Viewing which filters and slicers are currently applied to the visual.
• Opening the visual's options menu.

Sometimes it's useful to hide these actions. For instance, when two visuals overlap, you might not want to display both visuals' headers.

This API provides a way to hide or show headers of all the visuals in a report or only specific ones. You can configure the visibility on report load, or you can call the ReportupdateSettings method to change the visibility after a report has loaded, seeUpdate report settings at runtime.

You can use the API in many scenarios, including the following use cases:

• Hide only some of the visual headers in a report.
• Use business logic in an app, such as a button click, to hide or show a header after a report has loaded.

How to hide or show visual headers

To hide or show visual headers in the API, you configure certain parameters in a report's settings. SeeConfigure report settings for general information on configuring options in embedded reports.

Visual header settings

With visual headers, visibility is currently the only setting that you can configure. To hide or display headers, you provide a list of visual header configuration objects. Each one contains a settings object and can also include a selector.Selectors identify the visuals that you're applying the settings to. Learn more about selectors inSelectors.

The type of the configuration object that you provide to the API isIVisualSettings. Later in this article, you'll findexamples that show how to use this interface in your code.Power BI models lists all interface definitions that the examples use.

Note the following points:

• The selector is optional in these settings. When you don't list any selectors, the API applies your settings to all the visuals in the report.
• When you use selectors, you can specify visuals either by name or by type. To get the names and types of the visuals in a given page, use the PagegetVisuals method.

Precedence rules

The API applies configuration settings in the following order:

• Settings that are saved in the report.
• Settings that you define in the embed configuration object, which the API applies on load.
• Settings that you provide to theupdateSettings API.

If more than one setting can apply to a visual, the API uses the last setting that applies. TheHide all but one visual header example in the next section illustrates this point.

Examples

These examples show different ways of using the API to hide or show visual headers.

Hide all visual headers

This simple scenario provides customers with a clean report view by hiding all the visual headers in a report:

let embedConfig = {    ...    settings: {        ...        visualSettings: {            visualHeaders: [                {                    settings: {                        visible: false                    }                    /* No selector is listed. The API hides the headers of all the visuals in the report. */                }            ]        }    }};...let report = powerbi.embed(embedContainer, embedConfig);

Hide a specific visual's header

This example uses a selector to apply a visibility setting to a single visual. This scenario comes up when you want to hide functionality that doesn't make sense for a visual. Use this code in that case:

let embedConfig = {    ...    settings: {        ...        visualSettings: {            visualHeaders: [                {                    settings: {                        visible: false                    },                    selector: {                        $schema: "http://powerbi.com/product/schema#visualSelector",                        visualName: <The name of the visual>  // You can retrieve the name by using getVisuals.                    }                }            ]        }    }};...let report = powerbi.embed(embedContainer, embedConfig);

Hide all but one visual header

Use this code to hide all visual headers in a report except a specific visual's header:

let embedConfig = {    ...    settings: {        ...        visualSettings: {            visualHeaders: [                {                    settings: {                        visible: false                    }                    /* No selector is listed. The API hides the headers of all the visuals in the report. */                },                {                    settings: {                        visible: true                    },                    selector: {                        $schema: "http://powerbi.com/product/schema#visualSelector",                        visualName: <The name of the visual> // You can retrieve the name by using getVisuals.                    }                }            ]        }    }};...let report = powerbi.embed(embedContainer, embedConfig);

If you'd like to make more than one header visible, you can extend this code. Set up additional instances ofIVisualHeader with thevisible parameter insettings set totrue. For each visual that should have a visible header, add oneIVisualHeader instance to the list.

Considerations and limitations

• You can only control the visibility of visual headers if the report that you embed is in view mode.
• You can only hide or show a visual's entire header. You can't configure the visibility of specific items in the header menu.
• When you use a selector to specify a visual's name or type, use the PagegetVisuals method to obtain the visual's name, which is a unique identifier. Don't configure the selector with the visual's title.
• If a user saves a report that you embed with the API, the visual settings that you defined will be saved to the report. You can avoid this situation by configuring the report with a permission level ofView instead ofEdit orSave.

Related content

• Configure report settings
• Use selectors to control which visuals are affected
• get-visuals.md