Published on 2026-02-22

Vega-Lite Data Visualizations

A high-level grammar of interactive graphics, embedded securely in your Markdown files.

While Chart.js is perfect for standard business charts, Vega-Lite is designed for complex data analysis. It uses a “grammar of graphics” approach (similar to ggplot2 in R or D3.js) where you map data to visual properties (like the x-axis, y-axis, color, and size) using a strictly defined JSON syntax.

To embed a Vega-Lite graphic, wrap the valid JSON inside a vega or vega-lite fenced code block.

The Grammar of Graphics

In Vega-Lite, you define the dataset, the mark (how the data is drawn, e.g., point, line, bar), and the encoding (which data column maps to which visual channel).

A Basic Scatter Plot

syntax

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "A scatterplot showing horsepower and miles per gallons.",
  "data": {"url": "https://vega.github.io/editor/data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower", "type": "quantitative"},
    "y": {"field": "Miles_per_Gallon", "type": "quantitative"},
    "color": {"field": "Origin", "type": "nominal"},
    "shape": {"field": "Origin", "type": "nominal"}
  }
}

What makes the above code block powerful is the encoding. By simply stating "color": {"field": "Origin"}, Vega-Lite automatically analyzes the dataset, extracts the unique origins (USA, Europe, Japan), assigns them distinct colors, and generates a legend.

Bar Charts and Aggregation

Vega-Lite can perform data aggregation natively before plotting. Instead of pre-calculating the mean of your data, you can ask Vega-Lite to do it.

syntax

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "values": [
      {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
      {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53},
      {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
    "y": {"field": "b", "type": "quantitative"}
  }
}

Layering Marks

Because Vega-Lite uses a grammar structure, it’s trivial to layer a line on top of a bar chart.

syntax

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "A layered graphical representation.",
  "data": {
    "values": [
      {"date": "2023-01-01", "temp": 15},
      {"date": "2023-02-01", "temp": 17},
      {"date": "2023-03-01", "temp": 22},
      {"date": "2023-04-01", "temp": 28}
    ]
  },
  "layer": [
    {
      "mark": "bar",
      "encoding": {
        "x": {"field": "date", "type": "ordinal"},
        "y": {"field": "temp", "type": "quantitative"}
      }
    },
    {
      "mark": "line",
      "encoding": {
        "x": {"field": "date", "type": "ordinal"},
        "y": {"field": "temp", "type": "quantitative"},
        "color": {"value": "#BF0603"}
      }
    }
  ]
}

By embedding JSON directly into your Markdown files, you eliminate the need for external Excel sheets or Python scripts when generating dynamic, programmatic reports.