Power BI React Component

Common errors

• Error: You are running React 17. PowerBI-client-react v2 requires React 18 or higher.

  cause Mismatch between application's React version and `powerbi-client-react` peer dependency.
  fix Upgrade React and ReactDOM to version 18.x in your project (`npm install react@^18 react-dom@^18` or `yarn add react@^18 react-dom@^18`).

• ReferenceError: models is not defined

  cause `models` object from `powerbi-client` was not imported.
  fix Add `import * as models from 'powerbi-client';` to your component file.

• TypeError: Cannot read properties of undefined (reading 'detail')

  cause An event handler tried to access `event.detail` but the `event` object received did not have that property or was `undefined`.
  fix Ensure your event handler function correctly inspects the `event` object's structure as per `powerbi-client` documentation. Not all events might have a `detail` property, or it might be null.

• Power BI embed error: A token or embed URL is missing.

  cause The `embedConfig` prop is missing either `accessToken`, `embedUrl`, or `id` required for embedding.
  fix Verify that `embedConfig.accessToken`, `embedConfig.embedUrl`, and `embedConfig.id` are correctly populated with valid, non-empty string values from your Power BI embedding service.

Warnings

• breaking Version 2.0.0 and above now require React 18 as a peer dependency. Applications using older React versions will experience runtime errors or build failures.
  Fix: Upgrade your React application to React 18 or higher. If unable to upgrade, use `powerbi-client-react` v1.x.
• breaking In v2.0.0, the re-embed logic was fixed to ensure the component re-embeds correctly on every configuration change. This might alter existing behavior for applications that relied on previous, potentially incorrect, re-embedding patterns.
  Fix: Review existing code that relies on dynamic updates to `embedConfig` and ensure it behaves as expected with the new re-embed fix. No specific code fix is generally required as this corrects previous buggy behavior.
• gotcha The `models` object, crucial for `TokenType` and other configurations, is part of the `powerbi-client` library, not re-exported by `powerbi-client-react`. Forgetting to import it leads to runtime errors.
  Fix: Always explicitly import `models` using `import * as models from 'powerbi-client';` when needed in your components.
• gotcha When bootstrapping a Power BI entity, the `embedConfig` must initially have `accessToken: undefined` (or null/empty string). To actually embed the report after bootstrap, you *must* update the `embedConfig` props with a valid `accessToken` and other details.
  Fix: After initial bootstrap, ensure your component's state or props are updated with the necessary `accessToken`, `embedUrl`, and `id` to trigger the actual embedding process.
• gotcha Event handlers are passed as a `Map` object, not a plain JavaScript object. Incorrectly using a plain object will result in event handlers not being registered.
  Fix: Always use `new Map([...])` for the `eventHandlers` prop, e.g., `eventHandlers={new Map([['loaded', () => {...}]])}`.

Install

• npm install powerbi-client-react npm
• yarn add powerbi-client-react yarn
• pnpm add powerbi-client-react pnpm

Imports

• PowerBIEmbed
  wrong:

  const PowerBIEmbed = require('powerbi-client-react').PowerBIEmbed;

  correct:

  import { PowerBIEmbed } from 'powerbi-client-react';

  This is the primary React component for embedding Power BI content. CommonJS `require` is not officially supported for this ESM-first library.
• models
  wrong:

  import { models } from 'powerbi-client-react';

  correct:

  import * as models from 'powerbi-client';

  The `models` object containing enums like `TokenType` comes from the core `powerbi-client` library, not directly from `powerbi-client-react`. It must be imported separately.
• Report
  wrong:

  import { Report } from 'powerbi-client-react';

  correct:

  import { Report } from 'powerbi-client';

  Type definitions for embedded entities like `Report`, `Dashboard`, etc., are provided by the `powerbi-client` package and should be imported from there for TypeScript usage.

Quickstart

This quickstart demonstrates how to embed a Power BI report into a React component, including basic configuration, event handling, and accessing the embedded component reference. It uses environment variables for secure access.

import { PowerBIEmbed } from 'powerbi-client-react';
import * as models from 'powerbi-client';

function MyPowerBIReport() {
  const reportId = process.env.POWERBI_REPORT_ID ?? '';
  const embedUrl = process.env.POWERBI_EMBED_URL ?? '';
  const accessToken = process.env.POWERBI_ACCESS_TOKEN ?? '';

  if (!reportId || !embedUrl || !accessToken) {
    return <p>Please configure Power BI environment variables.</p>;
  }

  return (
    <div style={{ height: '600px', width: '100%' }}>
      <PowerBIEmbed
        embedConfig={{
          type: 'report',
          id: reportId,
          embedUrl: embedUrl,
          accessToken: accessToken,
          tokenType: models.TokenType.Embed,
          settings: {
            panes: {
              filters: {
                expanded: false,
                visible: false
              }
            },
            background: models.BackgroundType.Transparent
          }
        }}
        eventHandlers={
          new Map([
            ['loaded', () => console.log('Report loaded')],
            ['rendered', () => console.log('Report rendered')],
            ['error', (event) => console.error('Power BI error:', event.detail)],
            ['pageChanged', (event) => console.log('Page changed:', event.detail)]
          ])
        }
        cssClassName="my-powerbi-report"
        getEmbeddedComponent={(embeddedReport) => {
          console.log('Embedded component reference:', embeddedReport);
          // You can store this reference to interact with the report later
        }}
      />
    </div>
  );
}

export default MyPowerBIReport;