Share via

Embed a dashboard

  • Article

This article covers the steps for embedding a dashboard in your application. Learn more about dashboards in Introduction to dashboards for Power BI designers.

Tip

Try embedding a dashboard or experiment with our client APIs in the Explore our APIs section of the Power BI Embedded Analytics Playground.

How to embed a dashboard

When you embed Power BI content in an app, you use a configuration object to define the content that you're embedding and to specify the content's settings. Then you pass that object to the API.

When you embed a dashboard, use a configuration object of type IDashboardLoadConfiguration:

interface IDashboardLoadConfiguration {
    accessToken: string;
    embedUrl?: string;
    id: string;
    pageView?: models.PageView 
    tokenType?: models.TokenType;
    type: string;
}

This interface contains the following properties:

  • accessToken - The token that gives you access to the Power BI data that you're embedding. See Understand the different embedding solutions to learn more about access tokens.

  • embedUrl - The URL of the dashboard that you're embedding. This URL becomes the source of the HTML iframe element that contains the embedded dashboard. Specifically, the API assigns the URL to the src attribute of the iframe. You can use a Dashboards API to obtain this URL. Two examples are:

  • id - The ID of the dashboard that you're embedding. Use a Dashboards API to obtain this ID. For example:

  • pageView - The format that the API uses for the embedded dashboard. Possibilities include:

    • fitToWidth - The embedded dashboard's width matches the width of the div element that contains the dashboard.
    • oneColumn - The embedded dashboard appears in one column.
    • actualSize - The API displays the embedded dashboard at full size.

  • tokenType - The kind of token that gives you access to the Power BI data that you're embedding.

    • Use models.TokenType.Aad to embed for your organization (user owns data).
    • Use models.TokenType.Embed to embed for your customers (app owns data).

    See Understand the different embedding solutions for more information.

  • type - The kind of content that you're embedding. Use 'dashboard' for a dashboard.

Example

The following example shows you how to embed a single dashboard:

// Set up the configuration object that determines what to embed and how to embed it.
let embedConfiguration = {
    accessToken: anAccessToken,
    embedUrl: anEmbedUrl,
    id: aDashboardId,
    pageView: 'fitToWidth',
    tokenType: aTokenType,
    type: 'dashboard'
};
 
// Get a reference to the HTML element that contains the embedded dashboard.
let dashboardContainer = $('#dashboardContainer')[0];
 
// Embed the dashboard.
let dashboard = powerbi.embed(dashboardContainer, embedConfiguration);

Considerations and limitations

  • Embedding dashboards on EM SKUs is not supported

  • When you embed content, your app displays the content in a div element. If you use a pageView value of actualSize when you embed a dashboard:

    • If the dashboard is wider than the div element, the API uses the width of the div element as the width of the embedded dashboard.
    • If the dashboard is narrower than the div element, the API fills the unused space with the embedded background. By default, that background is white, but you can configure it to be transparent. In that case, the div element's styling is visible in the unused space.

Related content