Share via

Embedding a Power BI report with mobile layout

  • Article

Mobile users can view any Power BI report page in landscape orientation. However, report authors can create an additional view that is optimized for mobile devices and displays in portrait orientation. This design option, which is available in both Power BI Desktop and in the Power BI service, enables authors to select and rearrange just those visuals that make sense for mobile users on the go.

If your report has mobile layout that was created in Power BI Desktop or Power BI service, you can embed the report with this layout in your web application.

How to embed a report using mobile layout

First you need to create a mobile layout for your report, check out Optimize Power BI reports for the mobile app for creating this layout.

To embed a Power BI report in the report's mobile layout, you should set the layoutType to models.LayoutType.MobilePortrait in the settings object:

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

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

There are two layout types dedicated to mobile devices:

  • MobilePortrait - Optimized for portrait view. This is the mobile layout you created for your report.

  • MobileLandscape - Optimized for landscape view. This is the regular layout of your report.

Note

The report layout will be determined by the layoutType property regardless of the device actual orientation.

For example, the following code shows how to embed the report with a mobile layout.

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

var embedConfiguration = {
    type: 'report',
    id: reportId,
    embedUrl: embedUrl,
    tokenType: tokenType,
    accessToken: accessToken,
    settings: {
        layoutType: models.LayoutType.MobilePortrait
    }
};

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.

const newSettings = {
    layoutType: models.LayoutType.MobileLandscape
};

report.updateSettings(newSettings);

Check if a report page has mobile layout

The Power BI Client Page class, defines the hasLayout method as:

hasLayout(layoutType: any): Promise<boolean>

The hasLayout method will return a boolean if the page has the specified layout type.

let pages = await report.getPages();
let mobileLayout = pages[0].hasLayout(models.LayoutType.MobilePortrait);

You can use phased embedding with hasLayout in order to check if the page has mobile layout before rendering the report.

Swipe events

When embedding a report in mobile layout you can listen to the swipe events and run a custom code on your web application. There are two swipe events, swipeStart and swipeEnd both return the following format:

interface ISwipeEvent {
  currentPosition: IPosition;
  startPosition: IPosition;
}

interface IPosition {
  x: number;
  y: number;
}

For example, you can use the swipeEnd event to detect a left swipe:

report.on("swipeEnd", function(event) {
    const swipeEndEvent = event.detail.swipeEvent;
    if (swipeEndEvent.currentPosition.x < swipeEndEvent.startPosition.x) {
        console.log("Swipe left detected");
    }
});

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

Optimize your app with custom layouts

You can also use the custom layout feature to create a customized layouts that are optimized for different mobiles or tablet screens.

Considerations and limitations

  • After the report initial load, changing to report mobile layout is supported only if mobile layout (portrait/landscape) has been set into the initial embedding configuration object. Otherwise, you must first call powerbi.reset(HTMLElement) to remove the iframe. Then, you have to call powerbi.embed(...) using the same container with the mobile layout setting defined on the embedded configuration object.

  • If you try to embed a report page with the MobilePortrait layout and the page does not have a mobile layout, the page will be loaded with the MobileLandscape layout.

  • To allow your users to navigate between pages while using mobile layouts, you can use report.setPage and implement your own navigation. For more information, see Page navigation.

  • The above configurations refer to embedding a Power BI report in mobile view.
    Dashboard embed can be configured to mobile layout with the pageView configuration: pageView: 'oneColumn'

Related content