Share via

How to handle events

Tip

Experiment with APIs in real time using your own report or our sample report in the Developer sandbox section of the Power BI Embedded Analytics Playground.

Events are used to communicate between the Power BI component (for example, a report) and the web application code.

An embedded component emits events after an action is executed inside the component. These can be user interactions or an automated action (like a visual being rendered) within the component.

For example, buttonClicked is an event emitted by a Power BI report when a user clicks a button in the report. You can listen to the event by using report.on(...), and then set an event handler.

An example of how to handle an event

This example shows how to handle a report event. To learn about other types of events, see Events and their response values.

Note

Wait for the component to load before using the APIs. Listen to the loaded event and then issue new commands.

report.on('loaded', function(event)
{
    reportPages = await report.getPages();
});

How to remove event handlers

You can use report.off(...) to remove all event handlers for a specific event.

Events and their response values

View a full list of possible events and their response values.

Error events (relevant for all embeds)

An error event is emitted to describe a failed operation.

interface IError {
    message: string // A general message that describes the operation that failed (example: "Could not set page")
    detailedMessage?: string // Detailed message that describes the error
    errorCode?: string  //  Short message that describes the error
    level?: TraceType // The level of the error (example: 'Fatal')
    technicalDetails?: ITechnicalDetails
}

interface ITechnicalDetails {
    requestId?: string // Id for debugging - should be provided when reporting a bug
}

Note

Only the message property is required, and the other properties might be undefined.

Report events

A report event is emitted for an interaction with an embedded report, such as clicking a report button or rendering a visual.

buttonClicked

The buttonClicked event is raised when a user clicks on a Report button.

 id: string
 title?: string
 type?: string (type of button)
 bookmark?: string

commandTriggered

The commandTriggered event is raised when a user clicks on an extension command.

 command: string
 dataPoints?: IIdentityValue[]
 report: models.IReport
 page: models.IPage
 visual: models.IVisual

dataHyperlinkClicked

The dataHyperlinkClicked event is raised when a hyperlink is clicked, and the hyperlink's behavior is set to NavigateAndRaiseEvent or RaiseEvent.

 url: string
 report: models.IReport
 page: models.IPage
 visual: models.IVisual

For more information, see Configure report settings.

dataSelected

The dataSelected event is raised when a specific data point is selected. Range and relative slicers are not supported.

 report: models.IReport
 page: models.IPage
 visual: models.IVisual
 filters: IFilter[]
 dataPoints: IIdentityValue[]

loaded

The loaded event is raised when the report initializes. Loading is complete when the Power BI logo disappears.

pageChanged

The pageChanged event is raised whenever a page is changed.

 newPage: Models.IPage

rendered

The rendered event is raised when a report is fully rendered. For example, if all visuals are rendered upon loading a report or after a user interaction.

saveAsTriggered

When useCustomSaveAsDialog: true, the saveAsTriggered event is raised when a user clicks on Save As in the UI. This lets you create your own dialog for the Save As action.

saved

The saved event is raised when a save is triggered by a save or saveAs action in the UI or by using the APIs.

selectionChanged

The selectionChanged event is raised whenever the user is changing the selected visual. selectedItems is a list of all selected visuals when more than one is selected.

 report: models.IReport
 page: models.IPage
 visual?: models.IVisual
 selectedItems?: models.IVisual[]

visualClicked

The visualClicked event is raised every time a visual is clicked.

 report: models.IReport
 page: models.IPage
 visual: models.IVisual

visualRendered

The visualRendered event is raised when a visual is rendered (requires setting visualRenderedEvents to true in the settings object).

Note

Because visuals might render due to user interactions, it's recommended that this event only be turned on when needed.

 name: string

For more information, see Configure report settings.

Report Embed Mobile events

A Report Embed Mobile event is emitted for an interaction with an embedded report in a mobile layout, such as the beginning or end of a swipe.

swipeStart and swipeEnd events

swipeStart or swipeEnd events are raised when a user begins or ends a swipe movement on an embedded report.

interface ISwipeEvent {
    currentPosition: IPosition
    startPosition: IPosition
}

interface IPosition {
    x: number
    y: number
}

Dashboard events

A dashboard event is emitted when the dashboard is loaded and when a user clicks on a tile in the dashboard.

loaded

The loaded event is raised when the dashboard initializes.

tileClicked

The tileClicked event is raised when an end user clicks a tile. It is not raised for pinned live pages.

 tileId: string
 navigationUrl: string
 pageName: string
 reportEmbedUrl: string

Q&A events

A question and answer (Q&A) event is raised when a visual is rendered after entering a question.

visualRendered (Q&A)

The visualRendered event is raised when a visual is rendered after a question is entered and an answer displays.

 question: string
 normalizedQuestion: string

Tile events

A Tile event is raised when a user clicks on a tile.

tileClicked (tile event)

The tileClicked event is raised when an end user clicks a tile. It is not raised for pinned live pages.

 tileId: string
 navigationUrl: string
 pageName: string
 reportEmbedUrl: string

tileLoaded

The tileLoaded event is raised when the tile initializes. Loading is complete when the Power BI logo disappears.

Related content