Hide or show visual headers

  • Article

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 the Formatting section of the Visualizations pane called Visual header. You can use that card to turn the visual's header on and off. Learn more about visual headers in Visual 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 Report updateSettings method to change the visibility after a report has loaded, see Update 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. See Configure 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 in Selectors.

The type of the configuration object that you provide to the API is IVisualSettings. Later in this article, you'll find examples 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 Page getVisuals 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 the updateSettings API.

If more than one setting can apply to a visual, the API uses the last setting that applies. The Hide 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 of IVisualHeader with the visible parameter in settings set to true. For each visual that should have a visible header, add one IVisualHeader instance to the list.

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 Page getVisuals 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 of View instead of Edit or Save.

Next steps

Configure report settings

Use selectors to control which visuals are affected

get-visuals.md