Personalize a report layout

2025-04-03

With a custom report layout, you can embed a Power BI report with a different layout than what was saved in the original report. When you define a custom report layout, you can vary the size of a report page, and control the size, position, and visibility of visuals on the page.

Custom layout overview

To create a custom report layout, define a custom layout object and pass it to the settings object in an embed configuration.

In the settings object, set layoutType to models.LayoutType.Custom and set customLayout to your custom layout object:

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

For more information about report settings, see Configure report settings.

How to define a custom report layout

Each custom report layout is represented by a custom layout object that you define to specify the page size, canvas scale, and pages layout. Within the pages layout, you can specify a visual layout for each visual and a default visual layout for the report.

Custom layout interface definition

Use the ICustomLayout interface to define a custom layout object:

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

The ICustomLayout interface has the following properties:

pageSize - An IPageSize object that defines the page size of the canvas area for the report.
```
interface IPageSize {
    type: PageSizeType;
}
```
The IPageSize object uses the PageSizeType enum to set the page size:
```
enum PageSizeType {
    Widescreen,
    Standard,
    Cortana,
    Letter,
    Custom
}
```
displayOption - A DisplayOption enum that controls how to scale the canvas to fit in the frame.
```
enum DisplayOption {
    FitToPage,
    FitToWidth,
    ActualSize
}
```
pagesLayout - A PagesLayout object that controls the layout for each visual on a page. This property maps a page name to a PageLayout object. For more information, see Define a pages layout.
```
type PagesLayout = { [key: string]: IPageLayout; }
```

Define a pages layout

Use the IPageLayout interface to define a pages layout object. The interface enables you to define a visual layout map, which maps each visual name to a new layout object, and a default visual layout. Defining a pages layout is optional. If you don't provide a layout for a report, Power BI applies the default layout to the report. That is, the default layout is what applies to all the visuals that you don't specify in the visuals layout object. For example, you can initially hide all the visuals in a report, and then show selected visuals in the layout of your choice.

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

The IPageLayout interface has the following properties:

defaultLayout - An IVisualLayout object that defines the default visual layout. The default layout is automatically applied to all the visuals on the report page.
```
defaultLayout?: IVisualLayout
```
visualsLayout - A VisualsLayout object that defines a map between the visual names and visual layouts on the report page.
```
visualsLayout: VisualsLayout
```
```
VisualsLayout = { [key: string]: IVisualLayout; }
```

Define a visual layout

To define a visual layout, use the IVisualLayout interface to create a visual layout object and set its position, size, and visibility.

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

The IVisualLayout interface has the following properties:

x,y,z - Defines the x, y, and z coordinates of the visual.
width, height - Defines the width and height of the visual.
displayState - An IVisualContainerDisplayState object that defines the visibility of the visual.
```
interface IVisualContainerDisplayState {
    mode: VisualContainerDisplayMode;
}
```
The IVisualContainerDisplayState object uses the VisualContainerDisplayMode enum to set the visibility:
```
enum VisualContainerDisplayMode {
    Visible,
    Hidden
}
```

Update the layout

To update the report layout when the report is already loaded, use the report.updateSettings method. For more information, see Update report settings at runtime.

Example

This complete code example shows how to embed a report with a custom report layout. All visuals are hidden except for two visuals: VisualContainer1 and VisualContainer2. VisualContainer1 has a new layout, position, and size, while VisualContainer2 is visible with the report's default layout.

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

let embedConfig = {
    type: 'report',
    id: reportId,
    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
                            }
                        },
                    }
                }
            }
        }
    }
};
...
// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, embedConfig);

Share via