Custom JavaScript Visuals

When no built-in chart fits, a JS visual lets you draw it yourself from the visual's data, as HTML or as an ECharts chart.

What your code receives

Your code is the body of a function. It gets one argument, data, with the visual's query result:

FieldWhat it holds
data.dataThe rows, each an array of values in column order.
data.columnDetailsOne entry per column, with its name and column_type.

Returning HTML

Return a string of HTML. It replaces the visual's body. For example:

return '<div class="row">' +
  data.data.map((row) => '<div class="col">' + row[0] + '</div>').join('') +
'</div>';

Returning an ECharts chart

Return an ECharts option object instead of a string, and the visual draws it as an interactive chart, with tooltips and legend toggling working as ECharts provides them. The object must have series, dataset or graphic (or a timeline's baseOption and options). For example, a bar for each measure column, with the first column along the axis:

return {
  tooltip: { trigger: 'item' },
  legend: { top: 0 },
  xAxis: { type: 'category', data: data.data.map((row) => String(row[0])) },
  yAxis: { type: 'value' },
  series: data.columnDetails.slice(1).map((column, i) => ({
    name: column.name,
    type: 'bar',
    data: data.data.map((row) => row[i + 1])
  }))
};
  • No functions in the object. A formatter written as a function can't be returned and shows an error. Use ECharts' text templates instead, such as formatter: '{b}: {c}'.
  • The chart resizes with its tile. It uses the default chart colours unless the option sets its own color.
  • Clicking it does not drill down or filter other visuals, as built-in charts do. Number formats set in the visual's configuration don't apply; format numbers in the option.
  • An object that isn't an ECharts option shows an error in the visual, as does an option ECharts can't draw.

Click handlers

When your code returns HTML, an onclick="…" you write into it works when someone clicks the element, with this as the element and event as the click, and return false cancelling it as usual. A common use is a row that expands or collapses the rows under it.

ℹ️ Only handlers in your code run A handler runs only if its text is part of the visual's own code. If a value in the data happens to contain something like onclick=, it is shown but never run, so data can't add behaviour to your visual.

Limits

  • The code runs in the background, away from the page, and must finish within 5 seconds (an administrator can change this with JS_CUSTOM_VISUAL_EXECUTION_TIMEOUT).
  • It cannot use document, window, localStorage, fetch, XMLHttpRequest, timers, eval or Function, even in a comment. Build the result as a string or an object instead.