Custom Layout

ℹ️ 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 Personalize a report layout.

Use custom layout to embed a report with different layout than in original report. Defining a new layout varies between defining only a page size, or controlling visual sizes, position and visibility.

To define a custom layout, define custom layout object and pass it into settings object in embed configuration. In addition, set LayoutType to Custom. See Embed Configuration Details page for more details.

var embedConfig = {
    ...
    settings: {
        layoutType: models.LayoutType.Custom
        customLayout: {...}
    }
};

Custom Layout object Definition

interface ICustomLayout {
    pageSize?: IPageSize;
    displayOption?: DisplayOption;
    pagesLayout?: PagesLayout;
}

enum PageSizeType {
    Widescreen,
    Standard,
    Cortana,
    Letter,
    Custom
}

interface IPageSize {
    type: PageSizeType;
}

interface ICustomPageSize extends IPageSize {
    width?: number;
    height?: number;
}

enum DisplayOption {
    FitToPage,
    FitToWidth,
    ActualSize
}

• pageSize : use page size to control the canvas area size (i.e. report white area).
• displayOptions: possible values are: FitToWidth, FitToPage or ActualSize. It controls how to scale the canvas to fit into the iframe.
• pagesLayout: It controls the layout for each visual. see PagesLayout for more details.

Pages Layout

Defining pages layout object is basically defining a layout for each page, and for each page, you define a layout for each visual. PageLayout is optional: If you don't define a layout for a page, the default layout (which is saved in the report) will be applied.

pagesLayout is a map from page name to PageLayout object. definition:

    type PagesLayout = { [key: string]: IPageLayout; };

PageLayout contains a defaultLayout object which gives all the visuals a default layout. If default layout is not provided, the default layout for each visual will be as saved in report. In addition, PageLayout contains a visual layout map, which maps each visual name to a new layout object. This way, each visual can override the default layout differently.

interface IPageLayout {
  defaultLayout: IVisualLayout,
  visualsLayout: { [key: string]: IVisualLayout; };
}

Visual Layout

To define a visual layout, pass a new position and size and a new visibility state.

interface IVisualLayout {
  x?: number;
  y?: number;
  z?: number;
  width?: number;
  height?: number;
  displayState?: IVisualContainerDisplayState;
}

interface IVisualContainerDisplayState {
  mode: VisualContainerDisplayMode;
}

enum VisualContainerDisplayMode {
  Visible,
  Hidden
}

• x,y,z : defines the new position of the visual.
• width, height: defines the new size of the visual.
• displayState: defines the visibility of the visual.

Update Layout

You can use updateSettings method to update the report layout any time while the report is loaded. See Update Settings

Full code example

In this example, we will embed a report with a custom layout in which all visuals are hidden except two visuals. VisualContainer1: will get a new layout, new position and size. VisualContainer2: will be visible with the default layout saved in the report.

// Get models. models contains enums that can be used.
var models = window['powerbi-client'].models;

var embedConfiguration = {
	type: 'report',
	id: '5dac7a4a-4452-46b3-99f6-a25915e0fe55',
	embedUrl: 'https://app.powerbi.com/reportEmbed',
	tokenType: models.TokenType.Embed,
	accessToken: 'H4...rf',
	settings: {
		layoutType: models.LayoutType.Custom
		customLayout: {
			pageSize: {
				type: models.PageSizeType.Custom,
				width: 1600,
				height: 1200
			},
			displayOption: models.DisplayOption.ActualSize,
			pagesLayout: {
				"ReportSection1" : {
					defaultLayout: {
						displayState: {
							mode: models.VisualContainerDisplayMode.Hidden
						}
					},
					visualsLayout: {
						"VisualContainer1": {
							x: 1,
							y: 1,
							z: 1,
							width: 400,
							height: 300,
							displayState: {
								mode: models.VisualContainerDisplayMode.Visible
							}
						},
						"VisualContainer2": {
							displayState: {
								mode: models.VisualContainerDisplayMode.Visible
							}
						},
					}
				}
			}
		}
	}
};
 
// Get a reference to the embedded report HTML element
var embedContainer = document.getElementById('embedContainer');
 
// Embed the report and display it within the div container.
var report = powerbi.embed(embedContainer, embedConfiguration);

	...