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.
The following sections explain how to embed and configure Power BI content.
Provide configuration information
The IReportLoadConfiguration 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;
datasetBinding?: IDatasetBinding;
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.
To update the report settings when the report is already loaded, use the report.updateSettings
method. For more information, see Update report settings at runtime.
Panes
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 |
✔ | ✔ |
Filter pane
By default, the filter pane is visible. If you want to hide this pane, use the filterPaneEnabled
property, as shown in the following code:
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.
Page navigation pane
By default, the page navigation arrows are visible on embedded reports. To hide these arrows, use the navContentPaneEnabled
property, as shown in the following code:
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.
The page navigation pane appears at the bottom of the report, to use the new vertical pages pane you can set the position
property:
let embedConfig = {
...
settings: {
panes:{
pageNavigation: {
visible: true,
position: PagesPosition.Left
}
}
}
};
Note
You can't change the position of the page navigation pane using updateSettings
.
Bars
Set the visibility of the action bar and status bar by using the bars
property.
Action bar
The following code makes the action bar visible:
let embedConfig = {
...
settings: {
bars: {
actionBar: {
visible: true
}
}
}
};
Alternatively, in view mode, it's 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.
Status bar
The status bar holds the canvas zoom controller, which provides the ability to zoom on the canvas.
The following code makes the status bar visible:
let embedConfig = {
...
settings: {
bars: {
statusBar: {
visible: true
}
}
}
};
Locale settings
Use the localeSettings
property to specify the language and the formatting of the embedded report:
The language
property in localeSettings
consists of two parts of two letters each, separated by a hyphen:
- language defines the language that Power BI uses for localization. Examples of languages include en (English), es (Spanish), and tr (Turkish).
- locale defines the text formatting that Power BI uses for dates, currency, and other related content. Examples of locales include US (English), ES (Spain), and TR (Türkiye).
See Supported languages for a list of available languages and regions.
The following code assigns specific values to these localeSettings
:
let embedConfig = {
...
settings: {
localeSettings: {
language: "en-us"
}
}
};
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, 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
}
};
Hyperlink click behavior
You can control the behavior of a hyperlink in a table, or matrix out-of-the-box visuals. By default, the hyperlink opens a new window.
The behavior modes available:
enum HyperlinkClickBehavior {
Navigate,
NavigateAndRaiseEvent,
RaiseEvent
}
Navigate
- The URL is loaded into a new browsing context.NavigateAndRaiseEvent
- The URL is loaded into a new browsing context, and raises adataHyperlinkClicked
event.RaiseEvent
- Prevents the default behavior of URL click, and raisedataHyperlinkClicked
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, 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 more 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
You can control the filters that your app applies to an embedded report. By default, the report initially uses the filters that you saved to the report. However, you have two options if you want to adjust the filters:
Configure more filters to use together with the saved filters. The following code shows how to use the
filters
property to append more filters:let embedConfig = { ... filters: [...] };
Replace the saved filters with a new set. The
setFilters
method provides a way to dynamically change a report's filters. If you use this method during phased embedding, you can override the filters that the report initially applies. For more information about constructing filters and using thesetFilters
method, see Control report filters.
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 available:
enum ContrastMode {
None = 0,
HighContrast1 = 1,
HighContrast2 = 2,
HighContrastBlack = 3,
HighContrastWhite = 4
}
To configure a specific theme, use code similar to the following lines:
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.
Zoom level
To learn more about adjusting the report zoom level check the accessibility document.
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");
Considerations and limitations
Consider the following points when you configure embedded content:
The page navigation position can't be changed when the action bar is visible. Learn more about the action bar.
When you use the
bars
property in thesetting
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 thebars
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 apermissions
value ofRead,
the user won't 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 ofview,
the API fails to display content in edit mode.
- Configure a permission level with the
The panes property replaces the following
settings
properties:filterPaneEnabled
navContentPaneEnabled
If you use the
panes
property to configure filter or page navigation visibility, don't use thefilterPaneEnabled
ornavContentPaneEnabled
property in your app.The API can't apply a theme and a contrast level to embedded content at the same time. If you configure both options by using the
theme
andcontrastMode
properties, the API uses yourcontrastMode
value with the embedded content. However, the API ignores thetheme
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 thepageName
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.