Using the Vega-Lite editor in Chart Builder

Note

This guide covers basic customization in the Vega-Lite Editor. For more advanced features, explore the official Vega-Lite examples, tutorials, and full documentation.

Chart Builder supports advanced visual customization through the Vega-Lite Editor, which uses a JSON syntax for defining chart structure, appearance, and behavior. While the Visual Builder offers an easy, no-code experience for generating charts, the Vega-Lite Editor provides full control over your chart's configuration and styling.

Important

Once you switch to the Vega-Lite Editor and make manual changes, the Visual Builder becomes disabled for that chart. For the smoothest workflow, complete as much setup as possible in the Visual Builder first.

Getting started with Vega-Lite

This section assumes that you have already enabled the Chart Builder integration. If not, see the Enabling Chart Builder integration section in the main guide.

To start using the Vega-Lite Editor:

Go to the dataset or query you want to visualize and open it with Chart Builder.
We recommend building your initial chart in the Visual Builder first. For detailed steps, see the Creating a visualization from connected data section.
After the basic setup is complete, switch to the Vega-Lite Editor tab at the top of the screen.
The editor will display a live JSON specification of your chart. Changes are reflected immediately in the chart preview.

Customizing the chart title

By default, a Chart Builder adds the title automatically, but does not provide any graphical way to style it.

To enhance the appearance of your chart title:

Go to the Vega-Lite Editor mode.

Locate the top-level title property:

"title": "Historical High and Low Daily Temperatures Over Time"

To transform the title into a field that we can customize, make it into a JSON object by adding curly braces and adding the text property:
```
"title": {
  "text": "Historical High and Low Daily Temperatures Over Time"
}
```
The title will look the same as before, but we've laid the foundation for further styling by turning it into a JSON object.
Use the following properties to style the title:
- anchor — horizontal alignment:
  - start: aligns left
  - middle: centers (default)
  - end: aligns right
- font — name of the font
- fontSize — font size in pixels
- color — CSS-compatible hex or color name
- offset — spacing (in pixels) between title and chart
Final example
```
"title": {
   "text": "Historical High and Low Daily Temperatures Over Time",
   "anchor": "start",
   "font": "Lato",
   "fontSize": 24,
   "color": "#355D8A",
   "offset": 40
 }
```

Styling axis labels

To improve how axis labels appear in your chart—such as font size, font type, or color—use the config section in the Vega-Lite JSON.

To style axis labels:

Go to the Vega-Lite Editor mode.

At the root level of your JSON, locate the config block:

"config": {
  "background": "#ffffff",
  "padding": 20
}

Inside config, add the axis object to apply label styles to both X and Y axes. This sets a larger font size, applies a readable font, and colors the labels for better visibility:
```
"config": {
  "background": "#ffffff",
  "padding": 20,
  "axis": {
    "labelFontSize": 20,
    "labelFont": "Lato",
    "labelColor": "#6290C3"
  }
}
```
Use the following attributes for label styling:
- labelFontSize — font size of axis labels (in pixels)
- labelFont — font family for the label text
- labelColor — label text color (CSS-compatible hex or name)
To rotate labels on the X axis (useful when labels are long or crowded), add the axisX object and use the labelAngle property:
```
"config": {
  "background": "#ffffff",
  "padding": 20,
  "axis": {
    "labelFontSize": 20,
    "labelFont": "Lato",
    "labelColor": "#6290C3"
  },
  "axisX": {
    "labelAngle": 40
  }
}
```
This rotation tilts the X-axis labels by 40 degrees, improving readability when there is limited horizontal space.

Styling axis titles

To customize the font and appearance of axis titles, use the axis object inside the config section.

To style axis titles:

Go to the Vega-Lite Editor mode.

In the root-level config block, extend the axis object with title properties:

"config": {
  "background": "#ffffff",
  "padding": 20,
  "axis": {
    "labelFontSize": 20,
    "labelFont": "Lato",
    "labelColor": "#6290C3",
    "titleFontSize": 24,
    "titleColor": "#333D49",
    "titleFont": "Lato"
  }
}

Use the following properties to control how axis titles look:
- titleFont — font family for the axis title
- titleFontSize — font size in pixels
- titleColor — title text color (CSS-compatible)
These options help match your chart to brand styles or improve clarity.

Renaming axis titles

By default, Chart Builder uses raw field names (for example, state, gwh) as axis titles. You can override them with clean, readable labels.

To rename axis titles:

Go to the Vega-Lite Editor mode.
Scroll to the encoding block of your JSON.

Under "x" and "y", add the title property with your custom name:

"encoding": {
  "x": {
    "field": "state",
    "title": "State Name",
    "type": "nominal",
    "sort": {
      "field": "gwh",
      "op": "sum",
      "order": "descending"
    },
    "scale": {
      "type": "linear",
      "zero": true
    }
  },
  "y": {
    "field": "gwh",
    "title": "Gigawatt hours (GWh)",
    "type": "quantitative",
    "scale": {
      "type": "linear",
      "zero": true
    }
  }
}

This replaces technical field names with clean, user-friendly labels—ideal for charts shared with non-technical audiences.

In this section: