Visual header visibility

ℹ️ This wiki has been deprecated
All our Client APIs documentation and references can be found in the new Power BI embedded analytics Client APIs documentation set. For the content of this article see Hide or show visual headers.

Visual header visibility

Background

Sometimes, if you are embedding a report, you don’t want your users to do many of the actions that currently show in our visual header, such as opening the visual in focus mode, drilling down, export data and more. There is a way in Power BI Desktop to hide the visual header in reading view for all the visuals in a report. Additionally, this API gives you more control of this feature by allowing you to hide/show the visual header for all the report's visual or for specific visuals in the report, on report load or even after the report is loaded. Some examples for use- cases you can support using the API:

• Hide the visual header for all the visuals in the report without modifying the original report.
• Hide the header only for part of the visuals.
• Only specific group of users will see the visual header and will be able to use its functionality.
• Hide/Show the header after the report is loaded according to the app's business logic (e.g. clicking on a button in your app will hide/show the header).

Functionality

To implement the cases described above you should configure the appropriate parameters in the report settings (see Embed Configuration Details).

Configuration stage The definition of the settings can be done either:

• on report load
• on report rendering if you use phased loading
• after the report is rendered using Update Settings

Settings

In order to configure that, you can add a list of visual header settings and selectors. Currently, visibility is the only setting you can define for visual headers. For your convenience, we added code snippets in the Examples section of this document.

Visual header settings:
interface IVisualHeaderSettings {
    visible?: boolean;
}

Settings and selector:
interface IVisualHeader {
    settings: IVisualHeaderSettings;
    selector?: VisualsHeaderSelector;
}

Visual Settings:
interface IVisualSettings {
    visualHeaders?: IVisualHeader[];
}

Selectors

Selectors are the way to indicate on which objects the settings are applicable. The selector is optional, and when it doesn't appear, it means the settings are applicable for all the visuals in the report. The only type of selector supported now is a selector by visualName. It means that if you want to use it, you will need to know the visualName using GetVisuals.

Examples

1. Hide all Visual Headers in the report

This is the simplest scenario, useful if you want to give a clean report view for your customers. It can be done using the Power BI Desktop settings described at the top of this document. If you don’t want or can't change this setting in the report, you can do it using the API.

var embedConfig = {
    …
    settings: {
        filterPaneEnabled: false,
        navContentPaneEnabled: false,
        …
        visualSettings: {
            visualHeaders: [
                {
                    settings: {
                        visible: false
                    }
                    /* No selector - Hide visual header for all the visuals in the report */
                }
            ]
        }
    }
};
…
var report = powerbi.embed(embedContainer, embedConfig);

2. Hide visual header for a specific visual using visual selector

In this is scenario we use a selector to apply the visibility setting to a single visual or many visuals. It's useful if you want to hide functionalities to a specific visual if you consider it doesn't make sense. (example: you don’t want to allow Drill Down and Export Data to a visual of type Card).

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

3. Hide visual header for all the visuals in the report except a specific visual

If you want to make the header visible to a single or a list of single visuals and hide it for all the rest, you can do it in this manner:

var embedConfig = {
    …
    settings: {
        filterPaneEnabled: false,
        navContentPaneEnabled: false,
        …
        visualSettings: {
            visualHeaders: [
                {
                    settings: {
                        visible: false
                    }
                    /* No selector - Hide visual header for 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 using GetVisuals
                    }
                }
            ]
        }
    }
};
…
var report = powerbi.embed(embedContainer, embedConfig);

Precedence rules

1. API vs static configuration

Settings defined in the API are stronger than settings defined in Power BI Desktop. According to this rule, if the report has the "Hide visual header" option set to true in Power BI Desktop and is embedded with settings defining the visibility of the headers to true, the headers will be visible in View Mode despite the configuration.

2. Duplicates in settings list

If two settings in the settings list are applicable to the same visual, the latest setting will be applied.

Example:

• First setting: Hide for all the reports in the visual
• Second setting: Show header for visual named : "visual1"
• The two settings are applicable to "visual1". The latest one will be applied, and the header will be visible for "visual1".

Note: if we invert the order of the two settings, the header of "visual1" will be hidden.

3. Update Settings

A new settings list can be added using Update Settings. This list will be concatenated to the original settings list and their items considered newer than the original ones. Precedence will then follow the previous rule.

Example:

• Single setting in list on load: Hide for all the reports in the visual
• Single setting in list in Update Settings call after load: Show header for visual named : "visual1"
• The two settings are applicable to "visual1". The latest one will be applied, and the header will be visible for "visual1". All other visuals headers will be hidden.

Limitations & considerations

• Visual Headers cannot be hidden in 'Edit Mode'.
• You can only hide/show the whole visual header and there is no granular control for the visibility of the various commands in the menu
• Visual are only selectable by their visual names, more selectors will be available in the future (e.g. select by visual type).
• If you use visual name selectors, consider upgrading your report version to the latest Power BI Desktop version, to ensure visual name uniqueness.
• Visual names in selector should be get using GetVisuals API and not be mistaken with visual title or visual type.
• Be aware if you give Edit/Save permissions when you embed the report, the settings described in this page will be saved to the report in case the user save it.