Power BI JavaScript Client Library

To learn more about embedding Power BI and using the client APIs, use the following resources:

• Official Documentation: Power BI embedded analytics Client APIs documentation for embedding reports and using APIs.
• Code Docs: Detailed information about classes, interfaces, and types can be found in the code docs.
• Sample Applications: View real-world implementations in the PowerBI-Developer-Samples repository.
• Playground: Experiment with embedded analytics capabilities in the Power BI Embedded Analytics Playground.

You can install the powerbi-client library using NPM or NuGet depending on your project environment.

NPM Installation

For standard JavaScript/TypeScript projects:

npm install --save powerbi-client

To install the latest beta version:

npm install --save powerbi-client@beta

NuGet Installation

For .NET-based environments:

Install-Package Microsoft.PowerBI.JavaScript

Depending on your build pipeline, you can consume the library using ES6 imports or by including it as a global script.

Using ES6 Modules

If you use a module loader or a compilation step (like Webpack or Vite), import the entire namespace:

import * as pbi from 'powerbi-client';

Using a Global Script Tag

If you are not using a module loader, include the powerbi.js script before your closing </body> tag. This exposes the library as a global object.

When included directly, the library provides two globals:

1. powerbi-client: The library namespace.
2. powerbi: An instance of the service.

The IVisualNode interface defines the structure of a node within the Power BI report hierarchy. It is implemented by the VisualDescriptor class. A visual node contains metadata about its identity, type, and location within the report structure.

export interface IVisualNode {
  name: string;
  title: string;
  type: string;
  layout: IVisualLayout;
  page: IPageNode;
}

The Service class is the primary entry point for the Power BI Client SDK. It manages the lifecycle of all embedded components (Reports, Dashboards, Tiles, etc.) and handles communication between the host application and the embedded iframes. To use it, you typically instantiate it with the required communication factories (HPM, WPMP, and Router) and a configuration object.

// Note: This requires providing factories for the communication layer
// which are typically handled by the library's internal setup or specific integration patterns.
const service = new Service(hpmFactory, wpmpFactory, routerFactory, {
  autoEmbedOnContentLoaded: false,
  onError: (error) => console.error(error)
});

When instantiating the Service, you can provide an IServiceConfiguration object to control its behavior:

To improve perceived performance, use the preload method to load a Power BI iframe in the background. This creates a hidden iframe and triggers a preloaded custom event on the iframe once it has finished loading.

const iframe = service.preload(config, element);

iframe.addEventListener('preloaded', () => {
  console.log('Power BI content is preloaded and ready!');
});

Use the embed method to attach a Power BI component to a specific HTML element. You must provide an IComponentEmbedConfiguration which includes the embedUrl and the type of component (e.g., 'report', 'dashboard', 'tile', 'visual', or 'qna'). If the element already has a component attached, the service will reuse the existing instance and update it with the new configuration.

// Assuming 'service' is an instance of Service and 'container' is an HTMLElement
const config = {
  type: 'report',
  id: 'your-report-id',
  embedUrl: 'https://app.powerbi.com/reportEmbed...', 
  accessToken: 'YOUR_ACCESS_TOKEN'
};

const report = service.embed(container, config);

The getId() method retrieves the unique identifier for the Power BI dashboard. It attempts to find the ID in the following order of precedence:

1. The id property within the embed configuration object.
2. The powerbi-dashboard-id attribute on the HTML element used for embedding.
3. The dashboardId query parameter within the embedUrl.

If no ID is found in any of these locations, the method throws an error stating that the dashboard ID is required.

// Assuming 'dashboard' is an instance of the Dashboard class
try {
  const id = dashboard.getId();
  console.log("Dashboard ID:", id);
} catch (error) {
  console.error(error.message);
}

You can add custom commands to the report's context menus (right-click) or options menus. You can target specific visuals by name or type, and group commands together.

// Add context menu extension command
report.addContextMenuCommand(
  commandName, 
  commandTitle, 
  contextMenuTitle, 
  menuLocation, 
  visualName, 
  visualType, 
  groupName
);

// Add options menu extension command
report.addOptionsMenuCommand(
  commandName, 
  commandTitle, 
  optionMenuTitle, 
  menuLocation, 
  visualName, 
  visualType, 
  groupName, 
  commandIcon
);

// Remove a context menu command
report.removeContextMenuCommand(commandName, contextMenuTitle);

// Remove an options menu command
report.removeOptionsMenuCommand(commandName, optionsMenuTitle);

Use the render() method to display a report after it has been loaded via the powerbi.load() method. This is required when using the phased embedding API.

// Load report
var report = powerbi.load(element, config);

// ...

// Render report
report.render()