Configure report settings

By using the Power BI Client APIs, you can embed Power BI analytics in your application. When you use this client-side library to embed a Power BI report, you provide the API with information about that report.

You can use a configuration object to store information about your Power BI report. When you embed the report, you then pass that object to the API.

Besides giving the API access to the report, you can also use the configuration object to customize your report's appearance and behavior. For instance, you can adjust the filter visibility, navigation access, and location settings in the configuration object.

How to configure embedded content

The following sections explain how to embed and configure Power BI content.

Provide configuration information

This interface displays properties that a configuration object can supply to the Power BI Client APIs about a report:

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

See Embed a report for an explanation of this interface's required parameters and for code examples showing how to embed a report.

Customize settings

The following sections describe how you can use the settings property to adjust the appearance and behavior of your embedded Power BI report.

Panes

You can control the appearance of all the panes in your Power BI report with a single panes property, as shown in the following code:

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

From the following table, you can see which values each panes property supports:

Property Visible Expanded
bookmarks
fields
filters
pageNavigation
selection
syncSlicers
visualizations

Bars

You can set the visibility of the action bar by using the bars property.

The following code makes the action bar visible:

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

Alternatively, in view mode, it is also possible to use the actionBarEnabled URL parameter:

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

Note

In view mode the action bar is only supported for the embed for your organization scenario.

For the action bar in view mode it’s recommended to enable UserState.ReadWrite.All permission for your Azure AD application. This permission is required to allow end users to add the report to their favorites, and for enabling personal bookmarks and persistent filters.

Filter pane

By default, the filter pane is visible. However, you can hide this pane by using the filterPaneEnabled property, as the following code demonstrates:

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Note

The panes property replaces the filterPaneEnabled property. To maintain backward compatibility, the filterPaneEnabled property still exists. However, you should avoid using these two properties together.

By default, the page navigation arrows are visible on embedded reports. However, you can hide these arrows by using the navContentPaneEnabled property, as the following code demonstrates:

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

Note

The panes property replaces the navContentPaneEnabled property. To maintain backward compatibility, the navContentPaneEnabled property still exists. However, you should avoid using these two properties together.

Locale settings

You can use the localeSettings property to specify the language and the formatting of the embedded report:

  • The language property defines the language that Power BI uses for localization.
  • The formatLocale property defines the text formatting that Power BI uses for dates, currency, and other related content.

See Supported languages and countries/regions for Power BI for a list of available languages and regions.

The following code assigns specific values to these properties:

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en",
            formatLocale: "es"
        }
    }
};

Note

Locale settings cannot be changed after the report is loaded. To change the report locale settings, reset the iframe by calling powerbi.reset(element), and then embed the report again.

Transparent background

By default, the background of the embedded content is white with gray margins. If you prefer to use a different background, you can give the embedded content a transparent background. Then you can apply the style you want to the HTML div element that contains the embedded content. The div element's styling then becomes visible.

Use this code to make the background of the embedded content transparent:

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

You can control the behavior of a hyperlink in a table, or matrix out-of-the-box visuals. By default, the hyperlink will open a new window.

The behavior modes that are available are listed below:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}
  • Navigate - The URL will be loaded into a new browsing context.

  • NavigateAndRaiseEvent - The URL will be loaded into a new browsing context, and will raise a dataHyperlinkClicked event.

  • RaiseEvent - Prevents the default behavior of URL click, and raise dataHyperlinkClicked event.

Use this code to change the behavior of links to raise an event:

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

A dataHyperlinkClicked event fires when a hyperlink is clicked on an out-of-the-box table or matrix visuals and the behavior is either NavigateAndRaiseEvent or RaiseEvent.

report.on('dataHyperlinkClicked', () => {
    ...
});

For more information about handling events, see How to handle events.

Visual rendered events

You can listen to an event for each rendered visual. By default, the visual rendered events are disabled.

Use this code to make the visualRendered events triggered:

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

A visualRendered event fires when a visual is rendered and the visualRenderedEvents is enabled on the report settings.

report.on('visualRendered', () => {
    ...
});

For more information about handling events, see How to handle events.

Note

Because visuals might render due to user interactions, it's recommended to turn on this event only when needed.

Error messages

If you'd like to display customized error messages in embedded reports, you can use the hideErrors property to hide the default Power BI embedded error messages. Your code can then handle error events in a way that fits your app design. See Override default error messages for more information on overriding default errors.

Use this code to hide default error messages:

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

Customize options

The following sections describe how you can use additional properties to further customize the appearance and behavior of your embedded Power BI report.

Default page

You can control which page of your embedded report appears initially. By default, the initial page is the page that you modified most recently, which was the active page the last time you saved the report. You can override this behavior by using the pageName property and supplying it with the name of the page you'd like to display. However, if no page with that name exists in Power BI, the request to open it fails.

The following code shows how to configure your app to display a specific page:

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

On load filters

By default, the report will be loaded with its saved filters applied on it. However, you can adjust the applied filters for the active page or all the report pages.

Note

  • Both levels can be adjusted together.
  • Adjusting the filters for a specific visual or for another page can be done using the updateFilters method during phased embedding.

When adjusting the filters you need to pass the filter operation you want to preform. The available operations are:

  • RemoveAll - Removes all filters on the filter level.
  • ReplaceAll - Replaces all existing filters on the filter level with the given filters.
  • Add - Adds the given filters on the filter level (in addition to the existing filters).
  • Replace - Replaces an existing filter with a given filter only if both filters apply to the same data field. If there is a given filter that doesn't replace an existing filter, it will be added.
Adjusting active page filters

The following code shows how to update the active page filters on load:

let embedConfig = {
    ...
    filters: {
        currentPage: {
            operation: filterOperation,
            filters: [...] // Should be undefined for 'RemoveAll', and PageLevelFilters array for any other operations.
        }
    }
};
Adjusting all pages filters

The following code shows how to update the filters for all the pages of the report on load:

let embedConfig = {
    ...
    filters: {
        allPages: {
            operation: filterOperation,
            filters: [...] // Should be undefined for 'RemoveAll', and ReportLevelFilters array for any other operations.
        }
    }
};

On load slicers

You can control the state of the slicers that your app applies to an embedded report. By default, the API uses the slicers that you saved to the report. However, you can use the slicers property to modify the state of the existing slicers, as the following code demonstrates:

embedConfig = {
    ...
    slicers: slicerArray,
};

See Control report slicers for more information about modifying the state of a slicer.

On load bookmark

By using the bookmark property, you can apply a bookmark to an embedded report. See Bookmarks for more information about using bookmarks to capture the currently configured view of report pages.

You can specify the bookmark to use by providing either the bookmark name or the state. If you provide the bookmark name, your Power BI report needs to contain a saved bookmark with that name.

The bookmark property is of type IApplyBookmarkRequest. The following code shows this type's definition:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

This code shows how to specify a bookmark by name:

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

This code shows how to specify a bookmark by state:

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

Themes and high-contrast mode

You can control the theme and contrast level that your embedded content uses. By default, any content that you embed appears with the default theme and with zero contrast. You can override this behavior by configuring a specific theme or contrast level. For more information about themes, see Apply report themes.

The contrast modes that are available are listed below:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

Use code similar to the following lines to configure a specific theme:

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

The following code shows how to override the default contrast level, None:

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

Note

The API cannot apply a theme and a contrast level at the same time. If you configure both properties, the API uses the contrast level that you specified but ignores the theme setting.

Open in edit mode

By default, the report that you embed appears in view mode. However, you can override this behavior to open the report in edit mode. You can also switch between modes.

Configure edit mode

To open an embedded report in edit mode, use the viewMode property together with the permissions property.

You can assign the viewMode property the following values:

  • View - Opens the report in view mode.
  • Edit - Opens the report in edit mode.

You can assign the permissions property these values:

  • Read - Users can view the report.
  • ReadWrite - Users can view, edit, and save the report.
  • Copy - Users can save a copy of the report by using Save As.
  • Create - Users can create a new report.
  • All - Users can create, view, edit, save, and save a copy of the report.

When you configure content to open in edit mode, assign the permissions property a value that is appropriate for editing, as the following code demonstrates:

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

Note

The permissions value that you configure only works if the embed token that you acquired has sufficient privileges. For more information about embed tokens, see Create the embed token.

Switch between edit and view modes

Besides specifying a mode for embedded content to start in, you can also switch between edit and view modes dynamically.

If the content is in edit mode, and you'd like to switch to view mode, use this JavaScript code:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

If the content is in view mode, and you'd like to switch to edit mode, use this JavaScript code:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

Limitations

Consider the following points when you configure embedded content:

  • When you use the bars property in the setting property, as described in Bars, the API only applies your configuration if the embedded content is in edit mode. If your content is in view mode, the API ignores the bars setting.

  • When you use the viewMode property to display content in edit mode, you need to take two additional steps:

    • Configure a permission level with the permissions property. That permission level needs to give the user appropriate access for modifying content. For instance, if you assign a permissions value of Read, the user will not be able to edit content.
    • Ensure that the embed token that you generate has privileges that support editing. For instance, if you acquire a token with an accessLevel value of view, the API will fail to display content in edit mode.
  • The panes property replaces the following settings properties:

    • filterPaneEnabled
    • navContentPaneEnabled

    If you use the panes property to configure filter or page navigation visibility, do not use the filterPaneEnabled or navContentPaneEnabled property in your app.

  • The API cannot apply a theme and a contrast level to embedded content at the same time. If you configure both options by using the theme and contrastMode properties, the API uses your contrastMode value with the embedded content. However, the API ignores the theme setting.

  • If you want to apply a bookmark to an embedded report, you can use the bookmark property. If you supply a bookmark name with that property, the API can only use the bookmark if one exists with that name. Likewise, if you use the pageName property to specify an opening page, the API can only display that page if one exists with the given name. Before configuring a name, consider using an accessor method, such as the Report getPages method, to check whether a component exists with that name.

Next steps