Events
Power BI DataViz World Championships
Feb 14, 4 PM - Mar 31, 4 PM
With 4 chances to enter, you could win a conference package and make it to the LIVE Grand Finale in Las Vegas
Learn moreThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
The article describes the Visual API, and how Power BI handles the interactions between you, the visual, and the host.
Actions and subsequent updates in Power BI can be initiated manually or automatically. Update types:
The following figure shows how common visual-based actions, like selecting a bookmark, process in Power BI.
You can update a visual with Power BI as follows:
Open the visual's properties panel.
When you open the visual's properties panel, Power BI fetches supported objects and properties from the visual's capabilities.json file. To receive actual values of properties, Power BI calls the getFormattingModel
method of the visual (APIs earlier than version 5.0 call enumerateObjectInstances
instead). The API returns modern format pane model components, properties, and their actual values.
For more information, see Capabilities and properties of Power BI visuals.
Customize visualization titles, backgrounds, labels, and legends.
When you change the value of a property in the Format panel, Power BI calls the update
method. Power BI passes in the new options
object to the update
method, and the objects contain the new values.
For more information, see Objects and properties of Power BI visuals.
Resize the visual.
When you change the size of a visual, Power BI calls the update
method and passes in the new options
object. The options
objects have nested viewport
objects that contain the new width and height of the visual.
Apply a filter at the report, page, or visual level.
Power BI filters data based on filter conditions. Power BI calls the update
method of the visual to update the visual with new data.
The visual gets a new update of the options
objects when there's new data in one of the nested objects. How the update occurs depends on the data view mapping configuration of the visual.
For more information, see Understand data view mapping in Power BI visuals.
Select a data point in another visual in the report.
When you select a data point in another visual in the report, Power BI filters or highlights the selected data points and calls the visual's update
method. The visual gets new filtered data, or it gets the same data with an array of highlights.
For more information, see Highlight data points in Power BI Visuals.
Select a bookmark in the Bookmarks panel of the report.
When you select a bookmark in the Bookmarks panel, either:
Power BI calls a function that's passed and registered by the registerOnSelectionCallback
method. The callback function gets arrays of selections for the corresponding bookmark.
Power BI calls the update
method with a corresponding filter
object inside the options
object.
In both cases, the visual changes its state according to the received selections or filter
object.
For more information about bookmarks and filters, see Visual Filters API in Power BI visuals.
You can also interact directly with the visual to update it:
Hover over a data element.
A visual can display more information about a data point through the Power BI Tooltips API. When you hover over a visual element, the visual can handle the event and display data about the associated tooltip element. The visual can display either a standard tooltip or a report page tooltip.
For more information, see Add tooltips to your Power BI visuals.
Change visual properties (For example, by expanding a tree) and the visual saves the new state in the visual properties.
A visual can save properties values through the Power BI API. For example, when you interact with the visual and the visual needs to save or update properties values, the visual can call the persistProperties
method.
Select a URL.
By default, a visual can't open a URL directly. To open a URL in a new tab, the visual can call the launchUrl
method and pass the URL as a parameter.
For more information, see Create a launch URL.
Apply a filter through the visual.
A visual can call the applyJsonFilter
method and pass conditions to filter for data in other visuals. Several types of filters are available, including Basic, Advanced, and Tuple filters.
For more information, see Visual Filters API in Power BI visuals.
Select elements in the visual.
For more information about selections in a Power BI visual, see Add interactivity into visual by Power BI visual selections.
Sometimes the visual initiates communication with the Power BI host without any input from you:
A visual requests more data from Power BI.
A visual processes data part by part. The fetchMoreData
API method requests the next fragment of data in the semantic model.
For more information, see Fetch more data from Power BI.
The event service triggers.
Power BI can export a report to PDF or send a report by e-mail (applies only to certified visuals). To notify Power BI that rendering is finished and that the visual is ready to be captured as PDF or e-mail, the visual should call the Rendering Events API.
For more information, see Export reports from Power BI to PDF.
To learn about the event service, see "Rendering" events in Power BI visuals.
Interested in creating visualizations and adding them to Microsoft AppSource? See these articles:
Events
Power BI DataViz World Championships
Feb 14, 4 PM - Mar 31, 4 PM
With 4 chances to enter, you could win a conference package and make it to the LIVE Grand Finale in Las Vegas
Learn moreTraining
Module
Use visuals in Power BI - Training
Create and customize visuals to present data in compelling and insightful ways.
Certification
Microsoft Certified: Power BI Data Analyst Associate - Certifications
Demonstrate methods and best practices that align with business and technical requirements for modeling, visualizing, and analyzing data with Microsoft Power BI.
Documentation
Understand data view mapping in Power BI visuals - Power BI
Learn about single, categorical, and matrix data mapping. Specify the conditional requirements for data roles to create different types of visuals.
Capabilities and properties of Power BI visuals - Power BI
This article describes the capabilities.json file and properties of Power BI visuals that can be defined in the file.
Objects and properties of Power BI visuals - Power BI
This article explains which Power BI visual properties are customizable and how to customize the visual properties in the formatting pane.