Create a visual

  • Article

This API provides a way to create a new visual on a report page.

How to create a visual and bind it to data

Create an empty visual of a specific type, and then bind the visual to data fields. For a list of visual types, see out-of-the-box visual types.

Note

Visuals that are not installed in the visualization pane cannot be added to a report. This is true for both custom visuals that are not installed and out-of-the-box visuals that have been uninstalled.

  1. Configure the visual you want to create by using the following parameters:

    • Visual type: The type of visual you want to create, such as a barChart.
    • Layout (optional): The layout to be applied to the new visual.
    • autoFocus (optional): Choose whether or not the page automatically scrolls to the newly created visual (set to 'True' by default).

  2. Use the following method to create your visual:

    createVisual(visualType: string, layout?: models.IVisualLayout, autoFocus?: boolean): Promise<models.ICreateVisualResponse>

The returned value contains an object that represents the newly created visual. You can use the visual data binding and visual properties APIs to edit the visual according to your needs.

For example:

let createVisualResponse = await page.createVisual('areaChart');
let visual = createVisualResponse.visual;

Code examples

The following code examples show how to create visuals with different parameters.

Note

For information about creating custom layouts, see Visual layout.

Create an area chart visual with a custom layout and no focus.

const customLayout = {
    x: 20,
    y: 35,
    width: 1600,
    height: 1200
}

let createVisualResponse = await page.createVisual('areaChart', customLayout, false /* autoFocus */);

Create an area chart with a default layout.

let createVisualResponse = await page.createVisual('areaChart');

Available out-of-the-box visual types

  • actionButton

  • areaChart

  • barChart

  • basicShape

  • card

  • clusteredBarChart

  • clusteredColumnChart

  • columnChart

  • debugVisual

  • Decomposition Tree

  • donutChart

  • esriVisual

  • filledMap

  • funnel

  • gauge

  • hundredPercentStackedBarChart

  • hundredPercentStackedColumnChart

  • image

  • keyDriversVisual

  • kpi

  • lineChart

  • lineClusteredColumnComboChart

  • lineStackedColumnComboChart

  • map

  • multiRowCard

  • pieChart

  • pivotTable

  • PowerApps

  • pythonVisual

  • qnaVisual

  • ribbonChart

  • scatterChart

  • scriptVisual

  • shapeMap

  • slicer

  • stackedAreaChart

  • tableEx

  • textbox

  • treemap

  • waterfallChart

Limitations

Visual creation APIs are only available after the report is rendered. Listen on the report rendered event and trigger visual authoring APIs only after it is called. See Event handling for more information.

Next steps

Change the visual type

Configure data fields

Format visual properties