{"id":11574,"library":"powerbi-client-react","title":"Power BI React Component","description":"This library provides a React wrapper for the underlying `powerbi-client` JavaScript library, enabling seamless integration of various Power BI artifacts—reports, dashboards, tiles, visuals, Q&A, and paginated reports—directly within React applications. It also facilitates the creation of new Power BI reports within the application context. The current stable version is 2.0.2, with recent major updates like v2.0.0 upgrading the peer dependency to React 18, which introduced breaking changes for older React environments. Release cadence is driven by feature additions, bug fixes, and compatibility updates, without a strict schedule but maintaining active development. Its key differentiators include a declarative, component-based API that simplifies embedding compared to direct `powerbi-client` usage, built-in lifecycle management, and support for advanced features like report bootstrapping for performance optimization and dynamic configuration updates.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/microsoft/powerbi-client-react","tags":["javascript","microsoft","powerbi","embedded","react","typescript"],"install":[{"cmd":"npm install powerbi-client-react","lang":"bash","label":"npm"},{"cmd":"yarn add powerbi-client-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add powerbi-client-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the React component to function. v2.x requires React 18.","package":"react","optional":false},{"reason":"Underlying Power BI client library providing core embedding functionality, models, and types.","package":"powerbi-client","optional":false}],"imports":[{"note":"This is the primary React component for embedding Power BI content. CommonJS `require` is not officially supported for this ESM-first library.","wrong":"const PowerBIEmbed = require('powerbi-client-react').PowerBIEmbed;","symbol":"PowerBIEmbed","correct":"import { PowerBIEmbed } from 'powerbi-client-react';"},{"note":"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.","wrong":"import { models } from 'powerbi-client-react';","symbol":"models","correct":"import * as models from 'powerbi-client';"},{"note":"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.","wrong":"import { Report } from 'powerbi-client-react';","symbol":"Report","correct":"import { Report } from 'powerbi-client';"}],"quickstart":{"code":"import { PowerBIEmbed } from 'powerbi-client-react';\nimport * as models from 'powerbi-client';\n\nfunction MyPowerBIReport() {\n  const reportId = process.env.POWERBI_REPORT_ID ?? '';\n  const embedUrl = process.env.POWERBI_EMBED_URL ?? '';\n  const accessToken = process.env.POWERBI_ACCESS_TOKEN ?? '';\n\n  if (!reportId || !embedUrl || !accessToken) {\n    return <p>Please configure Power BI environment variables.</p>;\n  }\n\n  return (\n    <div style={{ height: '600px', width: '100%' }}>\n      <PowerBIEmbed\n        embedConfig={{\n          type: 'report',\n          id: reportId,\n          embedUrl: embedUrl,\n          accessToken: accessToken,\n          tokenType: models.TokenType.Embed,\n          settings: {\n            panes: {\n              filters: {\n                expanded: false,\n                visible: false\n              }\n            },\n            background: models.BackgroundType.Transparent\n          }\n        }}\n        eventHandlers={\n          new Map([\n            ['loaded', () => console.log('Report loaded')],\n            ['rendered', () => console.log('Report rendered')],\n            ['error', (event) => console.error('Power BI error:', event.detail)],\n            ['pageChanged', (event) => console.log('Page changed:', event.detail)]\n          ])\n        }\n        cssClassName=\"my-powerbi-report\"\n        getEmbeddedComponent={(embeddedReport) => {\n          console.log('Embedded component reference:', embeddedReport);\n          // You can store this reference to interact with the report later\n        }}\n      />\n    </div>\n  );\n}\n\nexport default MyPowerBIReport;","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your React application to React 18 or higher. If unable to upgrade, use `powerbi-client-react` v1.x.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always explicitly import `models` using `import * as models from 'powerbi-client';` when needed in your components.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `new Map([...])` for the `eventHandlers` prop, e.g., `eventHandlers={new Map([['loaded', () => {...}]])}`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Mismatch between application's React version and `powerbi-client-react` peer dependency.","error":"Error: You are running React 17. PowerBI-client-react v2 requires React 18 or higher."},{"fix":"Add `import * as models from 'powerbi-client';` to your component file.","cause":"`models` object from `powerbi-client` was not imported.","error":"ReferenceError: models is not defined"},{"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.","cause":"An event handler tried to access `event.detail` but the `event` object received did not have that property or was `undefined`.","error":"TypeError: Cannot read properties of undefined (reading 'detail')"},{"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.","cause":"The `embedConfig` prop is missing either `accessToken`, `embedUrl`, or `id` required for embedding.","error":"Power BI embed error: A token or embed URL is missing."}],"ecosystem":"npm"}