Embedding a Chart

You can embed a Zoomdata chart into a web page by using the visualize method of a client instance. The visualize method receives an object with the following properties:

  • config: A query configuration object
  • element: The HTML element to append the chart
  • source: A Zoomdata source model
  • variables: The charts variable configuration
  • visualization: The Zoomdata’s chart name to embed

The config object can be used to override the chart’s query. In a Zoomdata chart, the default query is generated from the definition of its query variables. If the variables definition should drive the chart’s query, the config object should include an empty filters array as its only property.

The element property is typically a DIV element.

The source model contains the definition of the Zoomdata data source. You can obtain the definition of the data source by using the sources.update method of the client instance.

The variables property is an object with the chart’s variable configuration. When overriding the query definition using the config object, the configuration should only include the constant variables.

Specify the visualization property by providing a string with the chart’s name (e.g. ‘Packed Bubbles’)

When embedding Zoomdata’s out of the box charts, ensure jQuery is available globally on the page. Most of the Zoomdata’s chart templates use jQuery methods, so this prevents errors from occurring.


// create an object with the Zoomdata source name to use when fetching the source model
// In our example, the source name = 'Sales'
const source = {
  name: 'Sales',

// helper function to retrieve the time player configuration settings
// from a source model
const getControlsCfg = source => {
  let { controlsCfg } = source;
  const playerControlCfg = controlsCfg && controlsCfg.playerControlCfg;
  if (!controlsCfg) {
    controlsCfg = {
      playerControlCfg: {},
      timeControlCfg: null,
  if (source.playbackMode) {
    controlsCfg.playerControlCfg = {
      pauseAfterRead: !source.live,
      timeWindowScale: playerControlCfg.timeWindowScale,
    if (!source.live) {
      controlsCfg.playerControlCfg.stopTime = '$end_of_data';
  return controlsCfg;

// helper function to retrieve the variable definitions
// from a source model
const getVisVariables = (source, chartName) =>
    visualization => visualization.name === chartName,

const embedChart = async () => {
  try {
    // create client
    const client = await ZoomdataSDK.createClient({ application, credentials });

    // fetch & cache source model in client instance
    // The update methods ensure this source is not refetched
    // in the future when us with the same client instance
    const sourceModel = (await client.sources.update(source))[0];

    // create the query configuration object
    const queryConfig = { filters: [] };

    const chartName = 'Packed Bubbles';
    const controlsCfg = getControlsCfg(sourceModel);
    const visVariables = getVisVariables(sourceModel, chartName);
    queryConfig.time = controlsCfg.timeControlCfg;
    queryConfig.player = controlsCfg.playerControlCfg;
    // use the visualize method to embed the chart
    const chart = await client.visualize({
      config: queryConfig,
      element: document.getElementById('root'),
      variables: visVariables,
      visualization: chartName,
  } catch (err) {


Try this example on CodeSandbox

It should embed the Packed Bubbles charts in the page.