Embed Configuration Details

The embed configuration is an object that describes what and how to embed.

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

export interface IReportCreateConfiguration {
  accessToken: string;
  datasetId: string;
  settings?: ISettings;
  tokenType?: TokenType;
}

export interface IDashboardLoadConfiguration {
  accessToken: string;
  id: string;
  pageView?: PageView;
  tokenType?: TokenType;
}

export interface ITileLoadConfiguration {
  accessToken: string;
  id: string;
  dashboardId: string;
  tokenType?: TokenType;
  width?: number;
  height?: number;
}

This object is used when calling powerbi.embed(element, embedConfiguration). The type is needed to know what type of embed to instantiate and the embedUrl is needed to set the source of the iframe.

When embedding, the minimum requirements are to have a type, embedUrl, accessToken and id. These can be specified in the embed configuration object as shown above or as attributes on the element which is why these properties are optional here. Read more about AccessToken and TokenType in Embedding Basics section.

There are additional properties settings, pageName, and filters.

Settings

All settings can be provided as attributes prefixed with powerbi-settings- on the containing HTML element.

1. Panes All of the panes in Power BI reports can be controlled with a single object:

   var 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
   			}
   		}
   	}
   };

   Note: This object is replacing the bookmarksPaneEnabled, filterPaneEnabled and navContentPaneEnabled properties, please avoid using them together.

   Supported values:

   	Visible	Expanded
   bookmarks	✔️	❌
   fields	❌	✔️
   filters	✔️	✔️
   pageNavigation	✔️	❌
   selection	✔️	❌
   syncSlicers	✔️	❌
   visualizations	❌	✔️

2. Filter Pane

   FilterPane is enabled/visible by default but can be disabled/hidden by adding the attribute on the element or specifying the setting in the embed configuration:

   <div ... powerbi-settings-filter-pane-enabled="false"></div>

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

3. Page Navigation

   Page navigation is enabled/visible by default but can be disabled/hidden by adding the attribute on the element or specifying the setting in the embed configuration:

   <div ... powerbi-settings-nav-content-pane-enabled="false"></div>

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

4. Locale Settings

   Locale settings are used to define the language and the formatting of the embedded report/dashboard. language defines the language that powerBI uses for localization. formatLocale defines the text formatting that powerBI uses for dates, currency etc.

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

5. Apply Bookmark on load Using bookmark on load feature you can apply a bookmark by name or by bookmark state. Applying a bookmark by name assumes you have a bookmark with the given name saved in your report. bookmark parameter is of type IApplyBookmarkRequest, which is defined as follows:

   type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;
   
   interface IApplyBookmarkStateRequest {
       state: string;
   }
   
   interface IApplyBookmarkByNameRequest {
       name: string;
   }

   Examples

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

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

6. Transparent Background By default, report background is white with gray margins. If default background does not look good into your application, use transparent background settings as follows:

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

   This way, You can give any style you want to the container div element, the report background will be transparent and the container div element will appear.

Options

1. Default Page By default the report will load the last modified page (i.e. the active page during the last save); however, this can be overwritten by specifying a specific page name.

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

2. Pre-applied Filters By default the report will load with the filters that are saved to the report; however, you can programmatically apply additional filters by setting the filters property. For more information about filters visit https://github.com/Microsoft/PowerBI-JavaScript/wiki/Filters.

   var embedConfig = {
     ...
     filters: [...]
   };

3. Themes and High Contrast Mode

   By default the report will load with the default theme, without contrast. You can choose to apply a theme or a contrast mode.

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

   You can learn more about themes by visiting Apply Report Themes section.

   The contrast modes available are:

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

   The default is None but you can change it.

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

   Note: if you supply both a theme and a contrast mode, only the contrast will be applied as they cannot be applied at the same time.

4. Opening in Edit mode By default the report will loaded in View mode. To open a report in Edit mode, pass viewMode parameter as Edit and give relevant permissions.

   var embedConfig = {
     ...
     permissions: models.Permissions.All
     viewMode: models.ViewMode.Edit

   viewMode possible values

   View - Opens report in View mode.

   Edit - Opens report in Edit mode.

   permissions possible values

   Read - Allows view report only.

   ReadWrite - Allows view, Edit and Save report.

   Copy - Allows Save a copy of a report using Save As.

   Create - Allows creating a new report.

   All - Allows everything.

   Note: permission passed in Load configuration works only if Embed Token acquired with relevant privileges.

   Switching between View and Edit mode

   You can use the following JavaScript to switch into view mode, if you are in edit mode

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

   You can use the following JavaScript to switch into edit mode, if you are in view mode

   // Switch to edit mode.
   report.switchMode("edit")