Skip to main content

Custom charts

Custom charts are available in Beta for those that want additional customization and an extended library of charts. The charts are powered by vega-lite - the link will take you to some example galleries of what you can build using this powerful charting library. This includes heat maps, bubble plots, box plots and more.

info

Custom visualizations in Lightdash are a Beta feature which means we have limited documentation and support. We may also change the way these options work in the future.

Enabling Custom Charts​

Custom charts need to be manually enabled in your project. Contact support for help!

Getting Started​

The general steps to create a custom chart are as follows:

  1. Return the data you need for your chart as normal using the Lightdash UI to select relevant dimensions and metrics.
  2. Head to the chart configuration options, in the drop down, you should see an option for custom charts as long as it has been enabled.
  1. You will see two tabs in the Configure chart section, one for Config, and one for Data. The Data tab should show the data you have in your results table in a JSON format, ready to be ingested by the Vega Lite config you supply in the Config tab.
  2. Add the config you need for your desired chart!

Below are some simple examples to show you how to get started with your first custom charts.

Note that if you are building from Vega-Lite examples, remove the data object from the chart config, as Lightdash automatically maps your results table to the visualization.

Bar chart​

You can already do this with presets in Lightdash, but it's a simple example you should be able to get working quickly.

  1. Return a dataset including one dimension, alongside a count for that dimension.
  2. Add the below to the Config tab, replacing the fields with the relevant field names from the Data tab.
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "mark": "bar",
  "encoding": {
    "y": {
      "field": "users_unique_users",
      "type": "quantitative"
    },
    "x": {
      "field": "users_job_title",
      "type": "ordinal"
    }
  }
}

Heatmaps​

Heatmaps can currently only be created using the Custom Charts feature. The following example shows how to build a simple heatmap that conveys the number of issues created in a Github repository over time.

  1. Return a dataset with two dimensions, and one metric.
  2. Add the below to the Config tab, replacing the fields with the relevant field names from the Data tab.
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "mark": "rect",
  "encoding": {
    "y": {
      "field": "github_daily_date_day_of_week_index",
      "type": "ordinal",
      "title": "Day of Week"
    },
    "x": {
      "field": "github_daily_date_week",
      "type": "temporal",
      "title": "Week"
    },
    "color": {
      "field": "github_daily_issues_created_num_total",
      "type": "quantitative",
      "aggregate": "sum",
      "title": "Issues Created"
    }
  }
}

You should output a heatmap with the standard Vega-Lite settings that looks like the one below:

Bubble Plots​

Bubble plots build on top of standard scatter plot visualizations, by allowing you to adjust the size of a given point based on the output of a field. Here's one looking at some Healthcare data.

  1. Return a dataset with one dimension, and three metrics.
  2. Add the below to the Config tab, replacing the fields with the relevant field names from the Data tab.
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "mark": "point",
  "encoding": {
    "x": {
      "field": "outpatient_charges_sum_total_paid",
      "type": "quantitative"
    },
    "y": {
      "field": "outpatient_charges_sum_number_services",
      "type": "quantitative"
    },
    "size": {
      "field": "outpatient_charges_diff_avg_estimate_vs_avg_payment",
      "type": "quantitative"
    }
  }
}

Below is the Bubble Plot generated from the code above! Experiment with further Vega-Lite settings to adjust things like Bubble size, colour and general formatting.